huang
6fc90abeb6
主要变更: 1. 新增 cmd/api/docs.go 实现文档自动生成逻辑 2. 修改 cmd/api/main.go 在服务启动时调用文档生成 3. 重构 cmd/gendocs/main.go 提取生成函数 4. 更新 .gitignore 忽略自动生成的 openapi.yaml 5. 新增 Makefile 支持 make docs 命令 6. OpenSpec 框架更新和变更归档 功能特性: - 服务启动时自动生成 OpenAPI 文档到项目根目录 - 保留独立的文档生成工具 (make docs) - 生成失败时记录错误但不影响服务启动 - 所有代码已通过 openspec validate --strict 验证 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
81 lines
2.6 KiB
Markdown
81 lines
2.6 KiB
Markdown
# error-handling Specification
|
||
|
||
## Purpose
|
||
TBD - created by archiving change refactor-framework-cleanup. Update Purpose after archive.
|
||
## Requirements
|
||
### Requirement: Simplified AppError Structure
|
||
|
||
系统 SHALL 简化 AppError 结构，删除冗余的 HTTPStatus 字段。
|
||
|
||
#### Scenario: AppError 字段
|
||
- **WHEN** 创建 AppError
|
||
- **THEN** 结构体只包含 3 个字段：
|
||
- Code: 业务错误码
|
||
- Message: 错误消息
|
||
- Err: 底层错误（可选）
|
||
|
||
#### Scenario: HTTP 状态码获取
|
||
- **WHEN** ErrorHandler 处理 AppError
|
||
- **THEN** 通过 GetHTTPStatus(code) 实时获取 HTTP 状态码
|
||
- **AND** 不从 AppError 字段中读取
|
||
|
||
#### Scenario: 禁止手动设置状态码
|
||
- **WHEN** 创建 AppError
|
||
- **THEN** 不提供 WithHTTPStatus() 方法
|
||
- **AND** Code 和 HTTPStatus 始终保持一致
|
||
|
||
### Requirement: Unified Error Response Format
|
||
|
||
系统 SHALL 使用统一的 JSON 响应格式（错误和成功均使用相同字段）。
|
||
|
||
#### Scenario: 响应结构
|
||
- **WHEN** 返回任何响应时
|
||
- **THEN** JSON 结构仅包含 4 个字段：
|
||
- code: 业务错误码（0 表示成功）
|
||
- msg: 消息（错误消息或 "success"）
|
||
- data: 响应数据（成功时有数据，错误时为 null）
|
||
- timestamp: ISO 8601 时间戳
|
||
|
||
#### Scenario: 不返回 HTTP 状态码字段
|
||
- **WHEN** 返回响应时
|
||
- **THEN** JSON 不包含 httpstatus 或 http_status 字段
|
||
- **AND** HTTP 状态码仅在响应头中体现
|
||
|
||
#### Scenario: Handler 返回错误
|
||
- **WHEN** Handler 函数返回 error
|
||
- **THEN** 全局 ErrorHandler 拦截错误
|
||
- **AND** 根据错误类型构造统一格式响应
|
||
|
||
### Requirement: Handler Error Return Convention
|
||
|
||
所有 Handler 函数 SHALL 通过返回 error 传递错误，由全局 ErrorHandler 统一处理。
|
||
|
||
#### Scenario: 业务错误
|
||
- **WHEN** Handler 遇到业务错误
|
||
- **THEN** 返回 errors.New(code, message) 创建的 AppError
|
||
- **AND** 不直接调用 response.Error()
|
||
|
||
#### Scenario: 参数验证错误
|
||
- **WHEN** 请求参数验证失败
|
||
- **THEN** 返回 errors.New(CodeInvalidParam, "具体错误描述")
|
||
|
||
#### Scenario: 成功响应
|
||
- **WHEN** Handler 执行成功
|
||
- **THEN** 调用 response.Success(c, data)
|
||
- **AND** 返回 nil
|
||
|
||
### Requirement: Standardized Error Codes
|
||
|
||
系统 SHALL 使用标准化的错误码，删除向后兼容的别名。
|
||
|
||
#### Scenario: 参数验证错误码
|
||
- **WHEN** 参数验证失败
|
||
- **THEN** 使用 CodeInvalidParam
|
||
- **AND** 不使用 CodeBadRequest（别名已删除）
|
||
|
||
#### Scenario: 服务不可用错误码
|
||
- **WHEN** 服务不可用
|
||
- **THEN** 使用 CodeServiceUnavailable
|
||
- **AND** 不使用 CodeAuthServiceUnavailable（别名已删除）
|
||
|