# 中间件系统

<cite>
**本文引用的文件**
- [server/src/app.ts](file://server/src/app.ts)
- [server/src/middleware/auth.ts](file://server/src/middleware/auth.ts)
- [server/src/middleware/errorHandler.ts](file://server/src/middleware/errorHandler.ts)
- [server/src/middleware/security.ts](file://server/src/middleware/security.ts)
- [server/src/middleware/rate-limiter.ts](file://server/src/middleware/rate-limiter.ts)
- [server/src/middleware/performance.ts](file://server/src/middleware/performance.ts)
- [server/src/middleware/cache.ts](file://server/src/middleware/cache.ts)
- [server/src/middleware/usageLimit.ts](file://server/src/middleware/usageLimit.ts)
- [server/src/types/index.ts](file://server/src/types/index.ts)
- [server/src/modules/auth/auth.controller.ts](file://server/src/modules/auth/auth.controller.ts)
- [server/src/modules/book-generator/langgraph-controller.ts](file://server/src/modules/book-generator/langgraph-controller.ts)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向“AI有声书生成平台”的后端中间件体系，围绕 Koa.js 中间件的设计与实现进行系统化梳理，重点覆盖以下方面：
- 中间件执行顺序与上下文传递机制
- 错误处理与统一异常模型
- 安全中间件的防护策略（XSS、SQL 注入、敏感数据脱敏）
- 限流中间件的流量控制策略与 Redis/内存回退
- 性能中间件的监控指标与慢请求告警
- 缓存中间件的命中与失效策略
- 使用次数与字数限额中间件的配额校验
- 中间件配置参数、自定义中间件开发指南与最佳实践
- 实际代码示例路径与调试方法

## 项目结构
中间件系统位于 server/src/middleware 目录，并在应用入口 server/src/app.ts 中集中注册。各中间件模块职责清晰、边界明确，通过 Koa 的洋葱模型串联，形成完整的请求生命周期。

```mermaid
graph TB
A["应用入口<br/>server/src/app.ts"] --> B["错误处理中间件<br/>errorHandler.ts"]
A --> C["Sentry 错误监控<br/>app.ts 内部调用"]
A --> D["性能监控中间件<br/>performance.ts"]
A --> E["HTTP 日志中间件<br/>app.ts 引入"]
A --> F["XSS 防护中间件<br/>security.ts"]
A --> G["SQL 注入防护中间件<br/>security.ts"]
A --> H["CORS 中间件<br/>app.ts"]
A --> I["Body/静态文件/上传中间件<br/>app.ts"]
A --> J["路由注册<br/>app.ts"]
J --> K["认证中间件必需<br/>auth.ts"]
J --> L["可选认证中间件<br/>auth.ts"]
J --> M["使用次数/字数限额中间件<br/>usageLimit.ts"]
J --> N["限流中间件按场景<br/>rate-limiter.ts"]
J --> O["缓存中间件按场景<br/>cache.ts"]
```

图表来源
- [server/src/app.ts:63-130](file://server/src/app.ts#L63-L130)
- [server/src/middleware/auth.ts:7-49](file://server/src/middleware/auth.ts#L7-L49)
- [server/src/middleware/security.ts:6-27](file://server/src/middleware/security.ts#L6-L27)
- [server/src/middleware/performance.ts:29-76](file://server/src/middleware/performance.ts#L29-L76)
- [server/src/middleware/errorHandler.ts:3-24](file://server/src/middleware/errorHandler.ts#L3-L24)
- [server/src/middleware/rate-limiter.ts:49-120](file://server/src/middleware/rate-limiter.ts#L49-L120)
- [server/src/middleware/cache.ts:13-48](file://server/src/middleware/cache.ts#L13-L48)
- [server/src/middleware/usageLimit.ts:7-49](file://server/src/middleware/usageLimit.ts#L7-L49)

章节来源
- [server/src/app.ts:63-130](file://server/src/app.ts#L63-L130)

## 核心组件
- 错误处理中间件：统一捕获异常，输出标准化响应，并在开发环境输出堆栈；提供多种业务错误类型。
- 安全中间件：XSS 防护、SQL 注入检测、敏感数据脱敏；设置安全响应头。
- 限流中间件：支持 Redis/内存双栈，内置多场景限流器（API、登录、短信、TTS、上传）。
- 性能中间件：统计总请求数、平均响应时间、慢请求、错误率与端点级指标。
- 缓存中间件：基于 Redis 的读写缓存与批量清空，支持自定义键生成器。
- 使用次数/字数限额中间件：基于用户会员等级的配额校验与状态注入。
- 认证中间件：基于 JWT 的强认证与可选认证（自动注入测试用户）。

章节来源
- [server/src/middleware/errorHandler.ts:3-67](file://server/src/middleware/errorHandler.ts#L3-L67)
- [server/src/middleware/security.ts:6-154](file://server/src/middleware/security.ts#L6-L154)
- [server/src/middleware/rate-limiter.ts:1-120](file://server/src/middleware/rate-limiter.ts#L1-L120)
- [server/src/middleware/performance.ts:1-110](file://server/src/middleware/performance.ts#L1-L110)
- [server/src/middleware/cache.ts:1-98](file://server/src/middleware/cache.ts#L1-L98)
- [server/src/middleware/usageLimit.ts:1-66](file://server/src/middleware/usageLimit.ts#L1-L66)
- [server/src/middleware/auth.ts:1-81](file://server/src/middleware/auth.ts#L1-L81)

## 架构总览
下图展示了请求在中间件链中的流转与关键节点：

```mermaid
sequenceDiagram
participant Client as "客户端"
participant App as "Koa 应用<br/>app.ts"
participant EH as "错误处理<br/>errorHandler.ts"
participant Perf as "性能监控<br/>performance.ts"
participant Sec as "安全中间件<br/>security.ts"
participant CORS as "CORS<br/>app.ts"
participant Body as "Body/静态/上传<br/>app.ts"
participant Route as "路由<br/>app.ts"
participant Auth as "认证中间件<br/>auth.ts"
participant Limit as "使用次数/字数限额<br/>usageLimit.ts"
participant RL as "限流中间件<br/>rate-limiter.ts"
participant Cache as "缓存中间件<br/>cache.ts"
participant Ctrl as "控制器<br/>auth.controller.ts"
Client->>App : "HTTP 请求"
App->>EH : "进入错误处理"
EH->>Perf : "进入性能监控"
Perf->>Sec : "进入安全中间件"
Sec->>CORS : "进入 CORS"
CORS->>Body : "进入 Body/静态/上传"
Body->>Route : "进入路由"
Route->>Auth : "进入认证中间件"
Auth->>Limit : "进入使用次数/字数限额"
Limit->>RL : "进入限流中间件"
RL->>Cache : "进入缓存中间件"
Cache->>Ctrl : "进入控制器"
Ctrl-->>Client : "响应"
Note over EH,Perf : "异常在 EH 中统一捕获并格式化"
Note over Perf,Cache : "性能指标在 Perf 中统计"
```

图表来源
- [server/src/app.ts:63-130](file://server/src/app.ts#L63-L130)
- [server/src/middleware/errorHandler.ts:3-24](file://server/src/middleware/errorHandler.ts#L3-L24)
- [server/src/middleware/performance.ts:29-76](file://server/src/middleware/performance.ts#L29-L76)
- [server/src/middleware/security.ts:6-27](file://server/src/middleware/security.ts#L6-L27)
- [server/src/middleware/auth.ts:7-49](file://server/src/middleware/auth.ts#L7-L49)
- [server/src/middleware/usageLimit.ts:7-49](file://server/src/middleware/usageLimit.ts#L7-L49)
- [server/src/middleware/rate-limiter.ts:49-120](file://server/src/middleware/rate-limiter.ts#L49-L120)
- [server/src/middleware/cache.ts:13-48](file://server/src/middleware/cache.ts#L13-L48)
- [server/src/modules/auth/auth.controller.ts:54-64](file://server/src/modules/auth/auth.controller.ts#L54-L64)

## 详细组件分析

### 认证中间件（JWT）
- 设计要点
  - 强制认证：要求 Authorization 头且格式为 Bearer Token，使用固定密钥验证；开发模式可通过开关跳过。
  - 可选认证：若携带有效 Token 则注入用户信息，否则注入测试用户（超级 VIP）。
  - 上下文传递：将用户信息注入 ctx.state.user，后续中间件可读取。
- 执行顺序
  - 在路由注册之前安装，确保所有受保护路由均经过认证。
- 错误处理
  - 缺失头、格式错误、过期或无效 Token 均抛出统一未授权错误。
- 实际使用示例
  - 受保护路由示例：[server/src/modules/auth/auth.controller.ts:54-64](file://server/src/modules/auth/auth.controller.ts#L54-L64)
  - 可选认证路由示例：[server/src/modules/book-generator/langgraph-controller.ts:519-573](file://server/src/modules/book-generator/langgraph-controller.ts#L519-L573)

```mermaid
flowchart TD
Start(["进入 authMiddleware"]) --> DevCheck{"开发模式启用？"}
DevCheck --> |是| InjectTest["注入测试用户<br/>ctx.state.user"]
InjectTest --> Next1["调用 next()"]
DevCheck --> |否| HasHeader{"存在 Authorization 头？"}
HasHeader --> |否| ThrowMissing["抛出未授权错误"]
HasHeader --> |是| ParseHeader["解析 Bearer Token"]
ParseHeader --> Verify["验证 JWT"]
Verify --> |成功| InjectUser["注入用户信息<br/>ctx.state.user"]
InjectUser --> Next2["调用 next()"]
Verify --> |失败| ThrowErr["抛出未授权或应用错误"]
Next1 --> End(["结束"])
Next2 --> End
ThrowMissing --> End
ThrowErr --> End
```

图表来源
- [server/src/middleware/auth.ts:7-49](file://server/src/middleware/auth.ts#L7-L49)

章节来源
- [server/src/middleware/auth.ts:1-81](file://server/src/middleware/auth.ts#L1-L81)
- [server/src/modules/auth/auth.controller.ts:54-64](file://server/src/modules/auth/auth.controller.ts#L54-L64)
- [server/src/modules/book-generator/langgraph-controller.ts:519-573](file://server/src/modules/book-generator/langgraph-controller.ts#L519-L573)

### 错误处理中间件（统一异常捕获）
- 设计要点
  - 包裹整个中间件链，捕获任意同步/异步错误。
  - 统一响应结构：code、message、data；开发环境附加 stack。
  - 提供多种业务错误类型：未授权、禁止访问、资源不存在、请求错误、配额超限等。
- 执行顺序
  - 最外层安装，确保所有错误被拦截与格式化。
- 实际使用示例
  - 控制器内主动抛错示例：[server/src/modules/auth/auth.controller.ts:14-16](file://server/src/modules/auth/auth.controller.ts#L14-L16)

```mermaid
flowchart TD
Enter(["进入 errorHandler"]) --> TryNext["尝试执行下游中间件/路由"]
TryNext --> |正常| Exit(["结束"])
TryNext --> |异常| Catch["捕获错误"]
Catch --> SetResp["设置状态码与响应体"]
SetResp --> DevEnv{"开发环境？"}
DevEnv --> |是| AddStack["附加堆栈信息"]
DevEnv --> |否| SkipStack["不附加堆栈"]
AddStack --> Exit
SkipStack --> Exit
```

图表来源
- [server/src/middleware/errorHandler.ts:3-24](file://server/src/middleware/errorHandler.ts#L3-L24)

章节来源
- [server/src/middleware/errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)
- [server/src/modules/auth/auth.controller.ts:14-16](file://server/src/modules/auth/auth.controller.ts#L14-L16)

### 安全中间件（XSS/SQL 注入/敏感数据脱敏）
- 设计要点
  - XSS 防护：递归清洗请求体与查询参数中的危险字符与脚本标签，设置安全响应头。
  - SQL 注入检测：对查询参数与请求体进行正则扫描，命中即拒绝。
  - 敏感数据脱敏：对响应体中常见敏感字段进行掩码处理。
- 执行顺序
  - 在路由之前安装，保证所有请求与响应均经过安全处理。
- 实际使用示例
  - XSS 防护中间件：[server/src/middleware/security.ts:6-27](file://server/src/middleware/security.ts#L6-L27)
  - SQL 注入防护中间件：[server/src/middleware/security.ts:61-84](file://server/src/middleware/security.ts#L61-L84)
  - 敏感数据脱敏中间件：[server/src/middleware/security.ts:105-133](file://server/src/middleware/security.ts#L105-L133)

```mermaid
flowchart TD
Start(["进入安全中间件"]) --> CleanBody["清洗请求体 XSS"]
CleanBody --> CleanQuery["清洗查询参数 XSS"]
CleanQuery --> SetHeaders["设置安全响应头"]
SetHeaders --> Next["调用 next()"]
Next --> After["下游执行完成"]
After --> MaskResp["脱敏响应中的敏感数据"]
MaskResp --> End(["结束"])
```

图表来源
- [server/src/middleware/security.ts:6-133](file://server/src/middleware/security.ts#L6-L133)

章节来源
- [server/src/middleware/security.ts:1-154](file://server/src/middleware/security.ts#L1-L154)

### 限流中间件（流量控制）
- 设计要点
  - 支持 Redis 与内存两种存储，Redis 不可用时自动回退。
  - 提供通用限流工厂与多场景限流器：API 全局、登录、短信、TTS、上传。
  - 超限时设置 Retry-After 并返回 429。
- 执行顺序
  - 在认证/配额之后、业务逻辑之前安装，避免绕过配额直接刷接口。
- 实际使用示例
  - 全局限流器：[server/src/middleware/rate-limiter.ts:77-81](file://server/src/middleware/rate-limiter.ts#L77-L81)
  - 登录限流器：[server/src/middleware/rate-limiter.ts:86-91](file://server/src/middleware/rate-limiter.ts#L86-L91)
  - 短信限流器：[server/src/middleware/rate-limiter.ts:96-101](file://server/src/middleware/rate-limiter.ts#L96-L101)
  - TTS 限流器：[server/src/middleware/rate-limiter.ts:106-110](file://server/src/middleware/rate-limiter.ts#L106-L110)
  - 上传限流器：[server/src/middleware/rate-limiter.ts:115-119](file://server/src/middleware/rate-limiter.ts#L115-L119)

```mermaid
flowchart TD
Start(["进入限流中间件"]) --> GenKey["生成限流键IP/用户/自定义"]
GenKey --> Consume["尝试消耗配额"]
Consume --> |成功| Next["调用 next()"]
Consume --> |失败| Reject["设置 429 与 Retry-After"]
Next --> End(["结束"])
Reject --> End
```

图表来源
- [server/src/middleware/rate-limiter.ts:49-72](file://server/src/middleware/rate-limiter.ts#L49-L72)

章节来源
- [server/src/middleware/rate-limiter.ts:1-120](file://server/src/middleware/rate-limiter.ts#L1-L120)

### 性能中间件（监控指标）
- 设计要点
  - 统计总请求数、平均响应时间、慢请求（阈值 1 秒）、端点级指标与错误率。
  - 提供获取指标与重置指标的辅助函数。
  - 在响应头中附加 X-Response-Time。
- 执行顺序
  - 在安全中间件之后、路由之前安装，覆盖全链路。
- 实际使用示例
  - 指标路由：[server/src/app.ts:96-98](file://server/src/app.ts#L96-L98)
  - 指标导出函数：[server/src/middleware/performance.ts:81-83](file://server/src/middleware/performance.ts#L81-L83)

```mermaid
flowchart TD
Start(["进入性能监控"]) --> MarkStart["记录开始时间"]
MarkStart --> CallNext["调用下游"]
CallNext --> |正常| Calc["计算耗时并更新指标"]
CallNext --> |异常| IncErr["增加错误计数并抛出"]
Calc --> Slow{"是否慢请求？"}
Slow --> |是| Warn["记录慢请求警告"]
Slow --> |否| SetHdr["设置 X-Response-Time"]
IncErr --> End(["结束"])
Warn --> SetHdr --> End
```

图表来源
- [server/src/middleware/performance.ts:29-76](file://server/src/middleware/performance.ts#L29-L76)

章节来源
- [server/src/middleware/performance.ts:1-110](file://server/src/middleware/performance.ts#L1-L110)
- [server/src/app.ts:96-98](file://server/src/app.ts#L96-L98)

### 缓存中间件（读写缓存）
- 设计要点
  - Redis 不可用时自动跳过缓存，不影响业务。
  - 支持自定义键生成器与键前缀，命中返回缓存、未命中写入缓存。
  - 提供批量清空缓存的中间件。
- 执行顺序
  - 在业务逻辑之前安装，优先读取缓存。
- 实际使用示例
  - 通用缓存工厂：[server/src/middleware/cache.ts:13-48](file://server/src/middleware/cache.ts#L13-L48)
  - 用户信息缓存：[server/src/middleware/cache.ts:68-72](file://server/src/middleware/cache.ts#L68-L72)
  - 书籍详情缓存：[server/src/middleware/cache.ts:81-85](file://server/src/middleware/cache.ts#L81-L85)

```mermaid
flowchart TD
Start(["进入缓存中间件"]) --> RedisAvail{"Redis 可用？"}
RedisAvail --> |否| Next["跳过缓存，直接调用 next()"]
RedisAvail --> |是| GenKey["生成缓存键"]
GenKey --> GetCache["尝试获取缓存"]
GetCache --> |命中| ReturnCache["设置 X-Cache=HIT 并返回缓存"]
GetCache --> |未命中| Exec["执行业务逻辑"]
Exec --> Ok{"状态码为 200 且有响应体？"}
Ok --> |是| SetCache["写入缓存带 TTL"]
Ok --> |否| Skip["不写入缓存"]
SetCache --> SetHdr["设置 X-Cache=MISS"]
Skip --> SetHdr
ReturnCache --> End(["结束"])
SetHdr --> End
Next --> End
```

图表来源
- [server/src/middleware/cache.ts:13-48](file://server/src/middleware/cache.ts#L13-L48)

章节来源
- [server/src/middleware/cache.ts:1-98](file://server/src/middleware/cache.ts#L1-L98)

### 使用次数/字数限额中间件（配额校验）
- 设计要点
  - 未登录时注入无限制配额；已登录则查询用户并重置当日使用次数。
  - 将用户配额与用户信息注入 ctx.state，供后续中间件与控制器使用。
  - 提供按字数的二次校验高阶中间件。
- 执行顺序
  - 在认证之后、业务逻辑之前安装，确保配额生效。
- 实际使用示例
  - 配额中间件：[server/src/middleware/usageLimit.ts:7-49](file://server/src/middleware/usageLimit.ts#L7-L49)
  - 字数校验高阶中间件：[server/src/middleware/usageLimit.ts:52-66](file://server/src/middleware/usageLimit.ts#L52-L66)
  - 会员配额定义：[server/src/types/index.ts:120-124](file://server/src/types/index.ts#L120-L124)

```mermaid
flowchart TD
Start(["进入使用次数/字数限额中间件"]) --> HasUserId{"是否存在用户ID？"}
HasUserId --> |否| InjectUnlim["注入无限制配额并继续"]
HasUserId --> |是| LoadUser["查询用户并重置当日使用次数"]
LoadUser --> CheckDaily{"是否超过日使用次数？"}
CheckDaily --> |是| ThrowQuota["抛出配额超限错误"]
CheckDaily --> |否| InjectQuota["注入用户配额与用户信息"]
InjectQuota --> Next["调用 next()"]
InjectUnlim --> Next
ThrowQuota --> End(["结束"])
Next --> End
```

图表来源
- [server/src/middleware/usageLimit.ts:7-49](file://server/src/middleware/usageLimit.ts#L7-L49)

章节来源
- [server/src/middleware/usageLimit.ts:1-66](file://server/src/middleware/usageLimit.ts#L1-L66)
- [server/src/types/index.ts:120-124](file://server/src/types/index.ts#L120-L124)

## 依赖关系分析
- 中间件耦合与内聚
  - 认证中间件与使用次数/字数限额中间件存在天然依赖：限额需要用户上下文。
  - 限流中间件依赖 Redis 服务；当 Redis 不可用时自动回退内存限流器。
  - 缓存中间件依赖 Redis 服务；不可用时自动跳过。
  - 错误处理中间件作为全局兜底，不依赖其他中间件。
- 外部依赖与集成点
  - Redis 服务：用于限流器与缓存。
  - Sentry：在应用启动时初始化，配合错误处理中间件统一上报。
  - Prisma：用于用户与配额查询。
  - JWT：用于认证中间件的令牌验证。

```mermaid
graph TB
subgraph "中间件"
A["auth.ts"] --> B["usageLimit.ts"]
B --> C["rate-limiter.ts"]
C --> D["cache.ts"]
E["errorHandler.ts"] -.->|.-> F["security.ts"]
F -.-> G["performance.ts"]
end
subgraph "外部服务"
R["Redis 服务"] --> C
R --> D
P["Prisma"] --> B
S["Sentry"] --> E
end
```

图表来源
- [server/src/middleware/auth.ts:1-81](file://server/src/middleware/auth.ts#L1-L81)
- [server/src/middleware/usageLimit.ts:1-66](file://server/src/middleware/usageLimit.ts#L1-L66)
- [server/src/middleware/rate-limiter.ts:1-120](file://server/src/middleware/rate-limiter.ts#L1-L120)
- [server/src/middleware/cache.ts:1-98](file://server/src/middleware/cache.ts#L1-L98)
- [server/src/middleware/errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)
- [server/src/middleware/security.ts:1-154](file://server/src/middleware/security.ts#L1-L154)
- [server/src/middleware/performance.ts:1-110](file://server/src/middleware/performance.ts#L1-L110)

章节来源
- [server/src/app.ts:13-25](file://server/src/app.ts#L13-L25)
- [server/src/middleware/rate-limiter.ts:1-3](file://server/src/middleware/rate-limiter.ts#L1-L3)
- [server/src/middleware/cache.ts:1-2](file://server/src/middleware/cache.ts#L1-L2)
- [server/src/middleware/usageLimit.ts:1-4](file://server/src/middleware/usageLimit.ts#L1-L4)

## 性能考量
- 中间件顺序对性能的影响
  - 错误处理与性能监控置于链路外层，避免重复统计与重复包裹。
  - 安全中间件在路由之前，减少无效请求进入业务逻辑的成本。
  - 限流与配额在路由之后、业务之前，避免无效计算与 IO。
- Redis 回退策略
  - 限流与缓存均具备 Redis 不可用时的回退逻辑，保障稳定性。
- 指标与告警
  - 性能中间件提供慢请求阈值与端点级指标，便于定位瓶颈。
- 最佳实践
  - 将热点接口与高并发接口优先接入缓存中间件。
  - 对登录、短信等易被攻击的接口单独配置限流器。
  - 在开发环境开启详细错误输出，生产环境关闭堆栈输出。

## 故障排查指南
- 常见问题与定位
  - 认证失败：检查 Authorization 头格式与 Token 是否过期；确认开发模式开关。
  - 429 频繁：检查限流键是否正确（IP/用户 ID），适当提高配额或延长窗口。
  - 缓存未生效：确认 Redis 连接状态与键前缀是否一致。
  - 慢请求告警：结合性能指标路由定位慢端点，优化数据库查询或第三方调用。
- 调试步骤
  - 查看 HTTP 日志与性能指标路由输出。
  - 在开发环境打开堆栈信息，快速定位异常源。
  - 使用 Sentry 错误监控查看异常聚合与告警。

章节来源
- [server/src/middleware/errorHandler.ts:19-22](file://server/src/middleware/errorHandler.ts#L19-L22)
- [server/src/middleware/performance.ts:60-63](file://server/src/middleware/performance.ts#L60-L63)
- [server/src/app.ts:96-98](file://server/src/app.ts#L96-L98)

## 结论
该中间件系统以 Koa 的洋葱模型为基础，构建了“安全—认证—配额—限流—缓存—性能—错误处理”的完整链路。通过模块化设计与可插拔组合，既满足了开发期的灵活性，也兼顾了生产期的稳定性与可观测性。建议在新增功能时遵循“前置安全、后置性能与错误兜底”的原则，确保中间件组合的一致性与可维护性。

## 附录

### 中间件配置参数与使用示例路径
- 认证中间件
  - 强制认证：[server/src/middleware/auth.ts:7-49](file://server/src/middleware/auth.ts#L7-L49)
  - 可选认证：[server/src/middleware/auth.ts:52-80](file://server/src/middleware/auth.ts#L52-L80)
- 错误处理中间件
  - 统一异常捕获与响应：[server/src/middleware/errorHandler.ts:3-24](file://server/src/middleware/errorHandler.ts#L3-L24)
  - 业务错误类型：[server/src/middleware/errorHandler.ts:27-67](file://server/src/middleware/errorHandler.ts#L27-L67)
- 安全中间件
  - XSS 防护：[server/src/middleware/security.ts:6-27](file://server/src/middleware/security.ts#L6-L27)
  - SQL 注入防护：[server/src/middleware/security.ts:61-84](file://server/src/middleware/security.ts#L61-L84)
  - 敏感数据脱敏：[server/src/middleware/security.ts:105-133](file://server/src/middleware/security.ts#L105-L133)
- 限流中间件
  - 通用工厂与场景限流器：[server/src/middleware/rate-limiter.ts:49-120](file://server/src/middleware/rate-limiter.ts#L49-L120)
- 性能中间件
  - 指标统计与导出：[server/src/middleware/performance.ts:29-110](file://server/src/middleware/performance.ts#L29-L110)
- 缓存中间件
  - 通用工厂与常用缓存配置：[server/src/middleware/cache.ts:13-98](file://server/src/middleware/cache.ts#L13-L98)
- 使用次数/字数限额中间件
  - 配额校验与字数校验：[server/src/middleware/usageLimit.ts:7-66](file://server/src/middleware/usageLimit.ts#L7-L66)
  - 会员配额定义：[server/src/types/index.ts:120-124](file://server/src/types/index.ts#L120-L124)

### 自定义中间件开发指南
- 设计原则
  - 明确职责单一，避免过度耦合。
  - 保持与 Koa 的 next 模式兼容，确保异常可被统一处理。
  - 对外暴露可配置参数，支持键生成器、TTL、阈值等。
- 开发步骤
  - 在 server/src/middleware 下新建文件，导出中间件函数。
  - 在 server/src/app.ts 中按需注册，注意顺序。
  - 在控制器中按需组合使用，必要时提供高阶中间件。
- 调试建议
  - 在关键节点打印 ctx.method、ctx.path、ctx.status、ctx.response.headers。
  - 使用性能中间件与指标路由观察影响范围。

### 中间件组合使用最佳实践
- 顺序建议
  - errorHandler → Sentry → performanceMonitor → httpLogger → xssProtection → sqlInjectionProtection → cors → koaBody/static/upload → router
  - 在路由层按需叠加：auth → usageLimit → rateLimiter → cache → controller
- 场景化组合
  - 登录接口：auth + loginRateLimiter
  - 文档/公开接口：optionalAuth + cache
  - 高频查询接口：cache + rateLimiter
  - 付费生成接口：auth + usageLimit + ttsRateLimiter + cache