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.1 KiB

Raw Blame History

auth Specification

Purpose

TBD - created by archiving change refactor-framework-cleanup. Update Purpose after archive.

Requirements

Requirement: Unified Authentication Middleware

系统 SHALL 提供统一的认证中间件，支持可配置的 Token 提取和验证。

Scenario: Token 验证成功

WHEN 请求携带有效的 Token
THEN 中间件提取并验证 Token
AND 将用户信息同时设置到 Fiber Locals 和 Context
AND 请求继续执行

Scenario: Token 缺失

WHEN 请求未携带 Token
AND 路径不在跳过列表中
THEN 返回 AppError（CodeMissingToken）
AND 由全局 ErrorHandler 处理错误响应

Scenario: Token 无效

WHEN 请求携带的 Token 无效或过期
THEN 返回 AppError（CodeUnauthorized）
AND 由全局 ErrorHandler 处理错误响应

Scenario: 跳过路径

WHEN 请求路径在 SkipPaths 配置中
THEN 中间件跳过认证
AND 请求直接继续执行

Requirement: User Context Management

认证中间件 SHALL 提供用户上下文管理函数，支持从 Context 获取用户信息。

Scenario: 获取用户 ID

WHEN 调用 GetUserIDFromContext(ctx)
AND 认证已通过
THEN 返回当前用户的 ID

Scenario: 检查 Root 用户

WHEN 调用 IsRootUser(ctx)
THEN 返回当前用户是否为 Root 用户

Scenario: 设置用户到 Fiber Context

WHEN 调用 SetUserToFiberContext(c, userInfo)
THEN 用户信息被设置到 Fiber Locals
AND 用户信息被设置到请求 Context（供 GORM 等使用）

Requirement: Auth Middleware Configuration

认证中间件 SHALL 支持灵活的配置选项。

Scenario: 自定义 Token 提取

WHEN 配置了 TokenExtractor 函数
THEN 使用自定义函数从请求中提取 Token

Scenario: 默认 Token 提取

WHEN 未配置 TokenExtractor
THEN 从 Authorization Header 提取 Bearer Token

Scenario: 自定义验证函数

WHEN 配置了 Validator 函数
THEN 使用自定义函数验证 Token 并返回用户信息

2.1 KiB Raw Blame History Unescape Escape