背景/痛点

在 OpenClaw 项目做深之后，很多团队会遇到一个典型问题：框架提供的默认能力够用，但不够贴合业务。

比如后台系统里常见的几个需求：

业务场景
默认能力的不足

多租户系统
每个接口都手写 tenantId 校验，容易漏

订单提交
重复点击、网络重试导致重复写入

审计合规
操作日志散落在业务代码中，后期难维护

灰度发布
路由规则和业务逻辑耦合，改动风险高

我在实际项目里踩过一个坑：某个批量导入接口没有统一做租户隔离，开发同学只在查询条件里补了 tenantId ，但更新逻辑漏掉了，最后导致跨租户数据被覆盖。这个问题不复杂，却很致命。

解决这类问题，最适合放在 OpenClaw 自定义中间件里。中间件的价值不只是“拦截请求”，更重要的是把横切逻辑从业务代码里抽出来，让业务代码只关注业务本身。

核心内容讲解

OpenClaw 的中间件模型可以理解为一条请求流水线：

请求进入

-> 租户识别中间件

-> 鉴权中间件

-> 幂等中间件

-> 审计中间件

-> 业务 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市场