lanyuanxiaoyao/nex
1
0
Fork 0
Code Activity
Files
aea360bce815a0f14f4e7ed930974eeb5ae5b19c
nex/openspec/specs/middleware-system/spec.md
lanyuanxiaoyao f18904af1e feat: 实现分层架构，包含 domain、service、repository 和 pkg 层 
- 新增 domain 层：model、provider、route、stats 实体
- 新增 service 层：models、providers、routing、stats 业务逻辑
- 新增 repository 层：models、providers、stats 数据访问
- 新增 pkg 工具包：errors、logger、validator
- 新增中间件：CORS、logging、recovery、request ID
- 新增数据库迁移：初始 schema 和索引
- 新增单元测试和集成测试
- 新增规范文档：config-management、database-migration、error-handling、layered-architecture、middleware-system、request-validation、structured-logging、test-coverage
- 移除 config 子包和 model_router（已迁移至分层架构）
2026-04-16 00:47:20 +08:00

3.5 KiB
Raw Blame History

Middleware System

ADDED Requirements

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 支持添加其他上下文信息
View Git Blame Copy Permalink