lanyuanxiaoyao
56ecc73d1b
将 cli-config、config-priority、env-config 合并入 config-management； 将 tdesign-integration、recharts-integration、frontend-config-ui、 frontend-testing、stats-dashboard 合并入新的 frontend/spec.md； 清理其余 spec 中的冗余标记，补充缺失场景。
139 lines
3.6 KiB
Markdown
139 lines
3.6 KiB
Markdown
# Middleware System
|
||
|
||
## Purpose
|
||
|
||
实现 HTTP 中间件体系，包括请求 ID、日志记录、错误恢复和 CORS 处理，确保请求的可追踪性、稳定性和跨域支持。
|
||
|
||
### Requirement: 实现请求 ID 中间件
|
||
|
||
系统 SHALL 实现请求 ID 中间件。
|
||
|
||
#### Scenario: 生成请求 ID
|
||
|
||
- **WHEN** 收到 HTTP 请求且 header 中无 X-Request-ID
|
||
- **THEN** SHALL 生成新的 UUID 作为请求 ID
|
||
- **THEN** SHALL 设置到响应 header 的 X-Request-ID
|
||
- **THEN** SHALL 设置到 gin.Context 中
|
||
|
||
#### Scenario: 复用请求 ID
|
||
|
||
- **WHEN** 收到 HTTP 请求且 header 中已有 X-Request-ID
|
||
- **THEN** SHALL 复用该请求 ID
|
||
- **THEN** SHALL 设置到响应 header
|
||
- **THEN** SHALL 设置到 gin.Context 中
|
||
|
||
### Requirement: 实现日志中间件
|
||
|
||
系统 SHALL 实现日志中间件。
|
||
|
||
#### Scenario: 记录请求开始
|
||
|
||
- **WHEN** 收到 HTTP 请求
|
||
- **THEN** SHALL 记录请求开始日志
|
||
- **THEN** SHALL 包含请求方法、路径、客户端 IP、请求 ID
|
||
|
||
#### Scenario: 记录请求结束
|
||
|
||
- **WHEN** HTTP 请求处理完成
|
||
- **THEN** SHALL 记录请求结束日志
|
||
- **THEN** SHALL 包含响应状态码、响应大小、请求耗时、请求 ID
|
||
|
||
#### Scenario: 记录错误
|
||
|
||
- **WHEN** 请求处理过程中发生错误
|
||
- **THEN** SHALL 记录错误日志
|
||
- **THEN** SHALL 包含错误详情和请求 ID
|
||
|
||
### Requirement: 实现错误恢复中间件
|
||
|
||
系统 SHALL 实现错误恢复中间件。
|
||
|
||
#### Scenario: 捕获 panic
|
||
|
||
- **WHEN** handler 发生 panic
|
||
- **THEN** SHALL 捕获 panic
|
||
- **THEN** SHALL 记录堆栈信息
|
||
- **THEN** SHALL 返回 500 错误响应
|
||
|
||
#### Scenario: 记录堆栈
|
||
|
||
- **WHEN** 发生 panic
|
||
- **THEN** SHALL 记录完整的堆栈信息
|
||
- **THEN** SHALL 包含 panic 原因和请求 ID
|
||
|
||
#### Scenario: 防止服务崩溃
|
||
|
||
- **WHEN** handler panic
|
||
- **THEN** SHALL 恢复并继续处理其他请求
|
||
- **THEN** SHALL NOT 导致服务崩溃
|
||
|
||
### Requirement: 实现 CORS 中间件
|
||
|
||
系统 SHALL 实现 CORS 中间件。
|
||
|
||
#### Scenario: 允许所有来源
|
||
|
||
- **WHEN** 收到 CORS 预检请求
|
||
- **THEN** SHALL 设置 Access-Control-Allow-Origin 为 *
|
||
- **THEN** SHALL 设置 Access-Control-Allow-Methods
|
||
- **THEN** SHALL 设置 Access-Control-Allow-Headers
|
||
|
||
#### Scenario: 处理预检请求
|
||
|
||
- **WHEN** 收到 OPTIONS 请求
|
||
- **THEN** SHALL 返回 204 状态码
|
||
- **THEN** SHALL 设置 CORS headers
|
||
|
||
注：当前配置允许所有来源，适合个人使用。
|
||
|
||
### Requirement: 中间件注册顺序
|
||
|
||
系统 SHALL 按正确顺序注册中间件。
|
||
|
||
#### Scenario: 全局中间件顺序
|
||
|
||
- **WHEN** 注册全局中间件
|
||
- **THEN** SHALL 按以下顺序注册：
|
||
1. RequestID（生成请求 ID）
|
||
2. Recovery（错误恢复）
|
||
3. Logging（日志记录）
|
||
4. CORS（跨域处理）
|
||
|
||
#### Scenario: 中间件执行顺序
|
||
|
||
- **WHEN** 处理请求
|
||
- **THEN** SHALL 按注册顺序执行中间件
|
||
- **THEN** SHALL 确保请求 ID 在其他中间件之前生成
|
||
|
||
### Requirement: 中间件配置
|
||
|
||
中间件 SHALL 支持配置。
|
||
|
||
#### Scenario: 日志中间件配置
|
||
|
||
- **WHEN** 初始化日志中间件
|
||
- **THEN** SHALL 注入 logger 实例
|
||
- **THEN** SHALL 使用配置的日志级别
|
||
|
||
#### Scenario: Recovery 中间件配置
|
||
|
||
- **WHEN** 初始化 recovery 中间件
|
||
- **THEN** SHALL 注入 logger 实例
|
||
- **THEN** SHALL 配置堆栈打印深度
|
||
|
||
### Requirement: 中间件上下文传递
|
||
|
||
中间件 SHALL 支持上下文传递。
|
||
|
||
#### Scenario: 请求 ID 传递
|
||
|
||
- **WHEN** 中间件设置请求 ID
|
||
- **THEN** SHALL 通过 gin.Context 传递
|
||
- **THEN** SHALL 在后续中间件和 handler 中可访问
|
||
|
||
#### Scenario: 日志上下文传递
|
||
|
||
- **WHEN** 日志中间件记录日志
|
||
- **THEN** SHALL 包含请求 ID
|
||
- **THEN** SHALL 支持添加其他上下文信息
|