这里写自定义目录标题
欢迎使用Markdown编辑器
背景/痛点
在 OpenClaw 项目做深之后，很多团队会遇到一个典型问题：框架提供的默认能力够用，但不够贴合业务。
比如后台系统里常见的几个需求：
业务场景
默认能力的不足
多租户系统
每个接口都手写 tenantId 校验，容易漏
订单提交
重复点击、网络重试导致重复写入
审计合规
操作日志散落在业务代码中，后期难维护
灰度发布
路由规则和业务逻辑耦合，改动风险高
我在实际项目里踩过一个坑：某个批量导入接口没有统一做租户隔离，开发同学只在查询条件里补了 tenantId ，但更新逻辑漏掉了，最后导致跨租户数据被覆盖。这个问题不复杂，却很致命。
解决这类问题，最适合放在 OpenClaw 自定义中间件里。中间件的价值不只是"拦截请求"，更重要的是把横切逻辑从业务代码里抽出来，让业务代码只关注业务本身。
核心内容讲解
OpenClaw 的中间件模型可以理解为一条请求流水线：
text
请求进入
-> 租户识别中间件
-> 鉴权中间件
-> 幂等中间件
-> 审计中间件
-> 业务 handler
响应返回
每个中间件通常做三件事：
读取上下文，比如 header、token、请求体
对上下文进行增强，比如写入当前租户、当前用户、请求追踪号
决定是否继续执行 next
进阶用法的关键在于：不要把中间件写成"杂货铺"。一个中间件只解决一类问题，并且要可配置、可测试、可观测。
我个人比较推荐下面这种拆分方式：
中间件
职责
tenantMiddleware
解析并校验租户
idempotentMiddleware
防重复提交
auditMiddleware
记录关键操作
traceMiddleware
注入链路追踪 ID
下面用一个较真实的案例：为订单创建接口增加"租户隔离 + 幂等控制 + 审计记录"。
实战代码/案例
假设 OpenClaw 的中间件签名类似 Koa：
```ts
type Middleware = function(ctx, next)
上下文 ctx 中包含 request 、 response 、 state 等对象。我们先实现租户中间件。
```ts
// tenant.middleware.ts
export function tenantMiddleware(options) {
const headerName = options.headerName || "x-tenant-id"
return async function tenant(ctx, next) {
const tenantId = ctx.request.headers.get(headerName)
// 没有租户信息，直接拒绝，避免进入业务层后再补救
if (!tenantId) {
ctx.response.status = 400
ctx.response.body = {
code: "TENANT_REQUIRED",
message: "缺少租户标识"
}
return
}
// 可以在这里接入缓存或数据库，校验租户是否有效
const tenant = await ctx.services.tenantService.findById(tenantId)
if (!tenant || tenant.disabled) {
ctx.response.status = 403
ctx.response.body = {
code: "TENANT_INVALID",
message: "租户不存在或已停用"
}
return
}
// 写入统一上下文，后续业务不再直接读 header
ctx.state.tenantId = tenantId
ctx.state.tenant = tenant
await next()
}
}
这个中间件的核心不是读取 header，而是建立一个约束：所有业务只能从 ctx.state.tenantId 获取租户。这样做的好处是后续排查问题非常清晰。
接着实现幂等中间件。订单创建、支付回调、优惠券领取都适合使用。
```ts
// idempotent.middleware.ts
export function idempotentMiddleware(options) {
const ttlSeconds = options.ttlSeconds || 60
return async function idempotent(ctx, next) {
const method = ctx.request.method
const path = ctx.request.path
const key = ctx.request.headers.get("idempotency-key")
// 只对写操作启用幂等校验
if (method !== "POST" && method !== "PUT") {
await next()
return
}
if (!key) {
ctx.response.status = 400
ctx.response.body = {
code: "IDEMPOTENCY_KEY_REQUIRED",
message: "缺少幂等键"
}
return
}
const tenantId = ctx.state.tenantId || "public"
const cacheKey = `idem:${tenantId}:${method}:${path}:${key}`
// Redis setNX：只有第一次请求能写入成功
const locked = await ctx.redis.setNX(cacheKey, "processing", ttlSeconds)
if (!locked) {
ctx.response.status = 409
ctx.response.body = {
code: "DUPLICATE_REQUEST",
message: "请求正在处理或已提交，请勿重复操作"
}
return
}
try {
await next()
// 成功后可记录结果状态，方便前端查询
await ctx.redis.set(cacheKey, "done", ttlSeconds)
} catch (err) {
// 失败时释放锁，允许用户修正参数后重试
await ctx.redis.del(cacheKey)
throw err
}
}
}
这里有一个实战细节：失败时是否删除幂等键，要根据业务决定。比如支付回调通常不删除，因为第三方会重试；但用户提交订单失败，删除更合理，否则用户可能被误拦截。
然后增加审计中间件。很多团队喜欢在 service 里写日志，我不太推荐，因为它会污染核心逻辑。
```ts
// audit.middleware.ts
export function auditMiddleware(options) {
return async function audit(ctx, next) {
const startedAt = Date.now()
let errorMessage = ""
try {
await next()
} catch (err) {
errorMessage = err.message
throw err
} finally {
const cost = Date.now() - startedAt
// 只记录配置过的关键接口，避免日志爆炸
const rule = options.rules.get(ctx.request.path)
if (!rule) {
return
}
await ctx.services.auditService.record({
tenantId: ctx.state.tenantId,
userId: ctx.state.userId,
action: rule.action,
path: ctx.request.path,
method: ctx.request.method,
status: ctx.response.status,
costMs: cost,
error: errorMessage,
ip: ctx.request.ip
})
}
}
}
最后在 OpenClaw 应用启动时注册中间件。
```ts
// app.ts
import { createApp } from "openclaw"
import { tenantMiddleware } from "./middlewares/tenant.middleware"
import { idempotentMiddleware } from "./middlewares/idempotent.middleware"
import { auditMiddleware } from "./middlewares/audit.middleware"
const app = createApp()
// 顺序很重要：先识别租户，再做幂等和审计
app.use(tenantMiddleware({
headerName: "x-tenant-id"
}))
app.use(idempotentMiddleware({
ttlSeconds: 120
}))
app.use(auditMiddleware({
rules: new Map()
.set("/api/orders", {
action: "ORDER_CREATE"
})
}))
app.post("/api/orders", async function createOrder(ctx) {
const tenantId = ctx.state.tenantId
const userId = ctx.state.userId
const body = await ctx.request.json()
// 业务层只关心创建订单，不再重复处理租户、幂等、审计
const order = await ctx.services.orderService.create({
tenantId: tenantId,
userId: userId,
skuId: body.skuId,
quantity: body.quantity
})
ctx.response.body = {
code: "OK",
data: order
}
})
app.listen(3000)
如果是生产环境，我还会补三点：
优化点
说明
中间件耗时监控
防止 Redis 或审计服务拖慢主链路
白名单机制
健康检查、登录接口不一定需要租户
降级策略
审计失败通常不应影响核心交易
例如审计中间件可以改成异步投递消息队列，而不是直接写数据库：
```ts
// 审计日志异步化，降低接口响应耗时
await ctx.messageQueue.publish("audit.log", {
tenantId: ctx.state.tenantId,
action: rule.action,
path: ctx.request.path,
status: ctx.response.status
})
总结与思考
OpenClaw 自定义中间件真正适合承载的是"横切型业务规则"，比如租户隔离、幂等、防刷、灰度、审计、链路追踪。它们有一个共同特征：每个接口都可能需要，但又不属于某个具体业务模块。
从工程角度看，中间件可以提升代码复用；从业务角度看，它能降低事故概率；从团队协作角度看，它把隐性规范变成了显性约束。尤其在多人协作和业务快速迭代的项目里，这种约束比文档更可靠。
我的经验是：不要一开始就追求大而全的中间件平台。先从一个高频痛点切入，比如幂等或租户隔离，把边界、异常、日志和配置做好。等模式稳定后，再抽象成团队级组件。技术扩展的价值，不在于写了多少框架代码，而在于它是否真正减少了重复劳动和线上风险。
云盏科技官网 #小龙虾 #云盏科技 #ai技术论坛 #skills市场你好！ 这是你第一次使用 **Markdown编辑器** 所展示的欢迎页。如果你想学习如何使用Markdown编辑器, 可以仔细阅读这篇文章，了解一下Markdown的基本语法知识。
## 新的改变
我们对Markdown编辑器进行了一些功能拓展与语法支持，除了标准的Markdown编辑器功能，我们增加了如下几点新功能，帮助你用它写博客：
1. **全新的界面设计** ，将会带来全新的写作体验；
2. 在创作中心设置你喜爱的代码高亮样式，Markdown **将代码片显示选择的高亮样式** 进行展示；
3. 增加了 **图片拖拽** 功能，你可以将本地的图片直接拖拽到编辑区域直接展示；
4. 全新的 **KaTeX数学公式** 语法；
5. 增加了支持**甘特图的mermaid语法[^1]** 功能；
6. 增加了 **多屏幕编辑** Markdown文章功能；
7. 增加了 **焦点写作模式、预览模式、简洁写作模式、左右区域同步滚轮设置** 等功能，功能按钮位于编辑区域与预览区域中间；
8. 增加了 **检查列表** 功能。
[^1]: [mermaid语法说明](https://mermaid.js.org/intro/)
## 功能快捷键
撤销：<kbd>Ctrl/Command</kbd> + <kbd>Z</kbd>
重做：<kbd>Ctrl/Command</kbd> + <kbd>Y</kbd>
加粗：<kbd>Ctrl/Command</kbd> + <kbd>B</kbd>
斜体：<kbd>Ctrl/Command</kbd> + <kbd>I</kbd>
标题：<kbd>Ctrl/Command</kbd> + <kbd>Shift</kbd> + <kbd>H</kbd>
无序列表：<kbd>Ctrl/Command</kbd> + <kbd>Shift</kbd> + <kbd>U</kbd>
有序列表：<kbd>Ctrl/Command</kbd> + <kbd>Shift</kbd> + <kbd>O</kbd>
检查列表：<kbd>Ctrl/Command</kbd> + <kbd>Shift</kbd> + <kbd>C</kbd>
插入代码：<kbd>Ctrl/Command</kbd> + <kbd>Shift</kbd> + <kbd>K</kbd>
插入链接：<kbd>Ctrl/Command</kbd> + <kbd>Shift</kbd> + <kbd>L</kbd>
插入图片：<kbd>Ctrl/Command</kbd> + <kbd>Shift</kbd> + <kbd>G</kbd>
查找：<kbd>Ctrl/Command</kbd> + <kbd>F</kbd>
替换：<kbd>Ctrl/Command</kbd> + <kbd>G</kbd>
## 合理的创建标题，有助于目录的生成
直接输入1次<kbd>#</kbd>，并按下<kbd>space</kbd>后，将生成1级标题。
输入2次<kbd>#</kbd>，并按下<kbd>space</kbd>后，将生成2级标题。
以此类推，我们支持6级标题。有助于使用`TOC`语法后生成一个完美的目录。
## 如何改变文本的样式
*强调文本* _强调文本_
**加粗文本** __加粗文本__
==标记文本==
~~删除文本~~
> 引用文本
H~2~O is是液体。
2^10^ 运算结果是 1024.
## 插入链接与图片
链接: [link](https://www.csdn.net/).
图片: 
带尺寸的图片: 
居中的图片: 
居中并且带尺寸的图片: 
当然，我们为了让用户更加便捷，我们增加了图片拖拽功能。
## 如何插入一段漂亮的代码片
去[博客设置](https://mp.csdn.net/console/configBlog)页面，选择一款你喜欢的代码片高亮样式，下面展示同样高亮的 `代码片`.
```javascript
// An highlighted block
var foo = 'bar';生成一个适合你的列表
- 项目
- 项目
- 项目
- 项目
- 项目1
- 项目2
- 项目3
- 计划任务
- 完成任务
创建一个表格
一个简单的表格是这么创建的：
| 项目 | Value |
|---|---|
| 电脑 | $1600 |
| 手机 | $12 |
| 导管 | $1 |
设定内容居中、居左、居右
使用:---------:居中
使用:----------居左
使用----------:居右
| 第一列 | 第二列 | 第三列 |
|---|---|---|
| 第一列文本居中 | 第二列文本居右 | 第三列文本居左 |
SmartyPants
SmartyPants 是一个文本转换工具，主要功能是将普通的 ASCII 标点符号自动转换为更美观的印刷体标点符号。例如：
| 原始符号 | 转换后 | 说明 |
|---|---|---|
"引号" |
"引号" | 直引号变弯引号 |
'单引号' |
'单引号' | 直单引号变弯单引号 |
-- |
-- | 两个连字符变短破折号 |
--- |
--- | 三个连字符变长破折号 |
... |
... | 三个点变省略号 |
创建一个自定义列表
:
Text-to- conversion tool
:
John
:
Luke
如何创建一个注脚
一个具有注脚的文本。[1](#1)
注释也是必不可少的
Markdown将文本转换为 。
KaTeX数学公式
您可以使用渲染LaTeX数学表达式 KaTeX:
Gamma公式展示 Γ ( n ) = ( n − 1 ) ! ∀ n ∈ N \Gamma(n) = (n-1)!\quad\forall n\in\mathbb N Γ(n)=(n−1)!∀n∈N 是通过欧拉积分
Γ ( z ) = ∫ 0 ∞ t z − 1 e − t d t . \Gamma(z) = \int_0^\infty t^{z-1}e^{-t}dt\,. Γ(z)=∫0∞tz−1e−tdt.
你可以找到更多关于的信息 LaTeX 数学表达式here.
新的甘特图功能，丰富你的文章
2014-01-07 2014-01-09 2014-01-11 2014-01-13 2014-01-15 2014-01-17 2014-01-19 2014-01-21 已完成 进行中 计划一 计划二 现有任务 Adding GANTT diagram functionality to mermaid
- 关于 甘特图 语法，参考 这儿,
UML图表
可以使用UML图表进行渲染，例如下面产生的一个序列图：
王五 李四 张三 王五 李四 张三 李四想了很长时间, 文字太长了 不适合放在一行. 你好！李四, 最近怎么样? 你最近怎么样，王五？ 我很好，谢谢! 我很好，谢谢! 打量着王五... 很好... 王五, 你怎么样?
- 关于 UML图表 语法，参考 这儿,
流程图
链接
长方形
圆
圆角长方形
菱形
- 关于 Mermaid 语法，参考 这儿,
FLowchart流程图
我们依旧会支持flowchart.js的流程图语法：
Created with Raphaël 2.3.0 开始 我的操作 确认？ 结束 yes no
- 关于 Flowchart流程图 语法，参考 这儿.
导出与导入
导出
如果你想尝试使用此编辑器, 你可以在此篇文章任意编辑。当你完成了一篇文章的写作, 在上方工具栏找到 文章导出 ，生成一个.md文件或者.html文件进行本地保存。
导入
如果你想加载一篇你写过的.md文件，在上方工具栏可以选择导入功能进行对应扩展名的文件导入，
继续你的创作。
- 注脚的解释 ↩︎
*[HTML]: 超文本标记语言