csxj2026/junhong_cmp_fiber

Files

huang 6fc90abeb6 实现服务启动时自动生成OpenAPI文档

主要变更:
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>

2026-01-09 12:25:50 +08:00

2.6 KiB

Raw Blame History

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（别名已删除）

2.6 KiB Raw Blame History Unescape Escape