csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects 1 Releases Wiki Activity

feat: OpenAPI 契约对齐与框架优化
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 5m45s
Details

Browse Source 
主要变更：
1. OpenAPI 文档契约对齐
   - 统一错误响应字段名为 msg（非 message）
   - 规范 envelope 响应结构（code, msg, data, timestamp）
   - 个人客户路由纳入文档体系（使用 Register 机制）
   - 新增 BuildDocHandlers() 统一管理 handler 构造
   - 确保文档生成的幂等性

2. Service 层错误处理统一
   - 全面替换 fmt.Errorf 为 errors.New/Wrap
   - 统一错误码使用规范
   - Handler 层参数校验不泄露底层细节
   - 新增错误码验证集成测试

3. 代码质量提升
   - 删除未使用的 Task handler 和路由
   - 新增代码规范检查脚本（check-service-errors.sh）
   - 新增注释路径一致性检查（check-comment-paths.sh）
   - 更新 API 文档生成指南

4. OpenSpec 归档
   - 归档 openapi-contract-alignment 变更（63 tasks）
   - 归档 service-error-unify-core 变更
   - 归档 service-error-unify-support 变更
   - 归档 code-cleanup-docs-update 变更
   - 归档 handler-validation-security 变更
   - 同步 delta specs 到主规范文件

影响范围：
- pkg/openapi: 新增 handlers.go，优化 generator.go
- internal/service/*: 48 个 service 文件错误处理统一
- internal/handler/admin: 优化参数校验错误提示
- internal/routes: 个人客户路由改造，删除 task 路由
- scripts: 新增 3 个代码检查脚本
- docs: 更新 OpenAPI 文档（15750+ 行）
- openspec/specs: 同步 3 个主规范文件

破坏性变更：无
向后兼容：是
This commit is contained in:
huang
2026-01-30 11:40:36 +08:00
parent 1290160728
commit 409a68d60b
88 changed files with 27358 additions and 990 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
internal/handler/admin/account.go
View File

@@ -25,7 +25,7 @@ func NewAccountHandler(service *accountService.Service) *AccountHandler {
}
// Create 创建账号
// POST /api/v1/accounts
// POST /api/admin/accounts
func (h *AccountHandler) Create(c *fiber.Ctx) error {
var req dto.CreateAccountRequest
if err := c.BodyParser(&req); err != nil {
@@ -41,7 +41,7 @@ func (h *AccountHandler) Create(c *fiber.Ctx) error {
}
// Get 获取账号详情
// GET /api/v1/accounts/:id
// GET /api/admin/accounts/:id
func (h *AccountHandler) Get(c *fiber.Ctx) error {
id, err := strconv.ParseUint(c.Params("id"), 10, 64)
if err != nil {
@@ -57,7 +57,7 @@ func (h *AccountHandler) Get(c *fiber.Ctx) error {
}
// Update 更新账号
// PUT /api/v1/accounts/:id
// PUT /api/admin/accounts/:id
func (h *AccountHandler) Update(c *fiber.Ctx) error {
id, err := strconv.ParseUint(c.Params("id"), 10, 64)
if err != nil {
@@ -78,7 +78,7 @@ func (h *AccountHandler) Update(c *fiber.Ctx) error {
}
// Delete 删除账号
// DELETE /api/v1/accounts/:id
// DELETE /api/admin/accounts/:id
func (h *AccountHandler) Delete(c *fiber.Ctx) error {
id, err := strconv.ParseUint(c.Params("id"), 10, 64)
if err != nil {
@@ -93,7 +93,7 @@ func (h *AccountHandler) Delete(c *fiber.Ctx) error {
}
// List 查询账号列表
// GET /api/v1/accounts
// GET /api/admin/accounts
func (h *AccountHandler) List(c *fiber.Ctx) error {
var req dto.AccountListRequest
if err := c.QueryParser(&req); err != nil {
@@ -109,7 +109,7 @@ func (h *AccountHandler) List(c *fiber.Ctx) error {
}
// AssignRoles 为账号分配角色
// POST /api/v1/accounts/:id/roles
// POST /api/admin/accounts/:id/roles
func (h *AccountHandler) AssignRoles(c *fiber.Ctx) error {
id, err := strconv.ParseUint(c.Params("id"), 10, 64)
if err != nil {
@@ -130,7 +130,7 @@ func (h *AccountHandler) AssignRoles(c *fiber.Ctx) error {
}
// GetRoles 获取账号的所有角色
// GET /api/v1/accounts/:id/roles
// GET /api/admin/accounts/:id/roles
func (h *AccountHandler) GetRoles(c *fiber.Ctx) error {
id, err := strconv.ParseUint(c.Params("id"), 10, 64)
if err != nil {
@@ -146,7 +146,7 @@ func (h *AccountHandler) GetRoles(c *fiber.Ctx) error {
}
// RemoveRole 移除账号的角色
// DELETE /api/v1/accounts/:account_id/roles/:role_id
// DELETE /api/admin/accounts/:account_id/roles/:role_id
func (h *AccountHandler) RemoveRole(c *fiber.Ctx) error {
accountID, err := strconv.ParseUint(c.Params("account_id"), 10, 64)
if err != nil {

23
internal/handler/admin/auth.go
View File

@@ -4,10 +4,12 @@ import (
"github.com/break/junhong_cmp_fiber/internal/model/dto"
"github.com/break/junhong_cmp_fiber/internal/service/auth"
"github.com/break/junhong_cmp_fiber/pkg/errors"
"github.com/break/junhong_cmp_fiber/pkg/logger"
"github.com/break/junhong_cmp_fiber/pkg/middleware"
"github.com/break/junhong_cmp_fiber/pkg/response"
"github.com/go-playground/validator/v10"
"github.com/gofiber/fiber/v2"
"go.uber.org/zap"
)
// AuthHandler 后台认证处理器
@@ -32,7 +34,12 @@ func (h *AuthHandler) Login(c *fiber.Ctx) error {
}
if err := h.validator.Struct(&req); err != nil {
return errors.New(errors.CodeInvalidParam, "参数验证失败: "+err.Error())
logger.GetAppLogger().Warn("参数验证失败",
zap.String("path", c.Path()),
zap.String("method", c.Method()),
zap.Error(err),
)
return errors.New(errors.CodeInvalidParam)
}
clientIP := c.IP()
@@ -77,7 +84,12 @@ func (h *AuthHandler) RefreshToken(c *fiber.Ctx) error {
}
if err := h.validator.Struct(&req); err != nil {
return errors.New(errors.CodeInvalidParam, "参数验证失败: "+err.Error())
logger.GetAppLogger().Warn("参数验证失败",
zap.String("path", c.Path()),
zap.String("method", c.Method()),
zap.Error(err),
)
return errors.New(errors.CodeInvalidParam)
}
ctx := c.UserContext()
@@ -130,7 +142,12 @@ func (h *AuthHandler) ChangePassword(c *fiber.Ctx) error {
}
if err := h.validator.Struct(&req); err != nil {
return errors.New(errors.CodeInvalidParam, "参数验证失败: "+err.Error())
logger.GetAppLogger().Warn("参数验证失败",
zap.String("path", c.Path()),
zap.String("method", c.Method()),
zap.Error(err),
)
return errors.New(errors.CodeInvalidParam)
}
ctx := c.UserContext()

12
internal/handler/admin/permission.go
View File

@@ -23,7 +23,7 @@ func NewPermissionHandler(service *permissionService.Service) *PermissionHandler
}
// Create 创建权限
// POST /api/v1/permissions
// POST /api/admin/permissions
func (h *PermissionHandler) Create(c *fiber.Ctx) error {
var req dto.CreatePermissionRequest
if err := c.BodyParser(&req); err != nil {
@@ -39,7 +39,7 @@ func (h *PermissionHandler) Create(c *fiber.Ctx) error {
}
// Get 获取权限详情
// GET /api/v1/permissions/:id
// GET /api/admin/permissions/:id
func (h *PermissionHandler) Get(c *fiber.Ctx) error {
id, err := strconv.ParseUint(c.Params("id"), 10, 64)
if err != nil {
@@ -55,7 +55,7 @@ func (h *PermissionHandler) Get(c *fiber.Ctx) error {
}
// Update 更新权限
// PUT /api/v1/permissions/:id
// PUT /api/admin/permissions/:id
func (h *PermissionHandler) Update(c *fiber.Ctx) error {
id, err := strconv.ParseUint(c.Params("id"), 10, 64)
if err != nil {
@@ -76,7 +76,7 @@ func (h *PermissionHandler) Update(c *fiber.Ctx) error {
}
// Delete 删除权限
// DELETE /api/v1/permissions/:id
// DELETE /api/admin/permissions/:id
func (h *PermissionHandler) Delete(c *fiber.Ctx) error {
id, err := strconv.ParseUint(c.Params("id"), 10, 64)
if err != nil {
@@ -91,7 +91,7 @@ func (h *PermissionHandler) Delete(c *fiber.Ctx) error {
}
// List 查询权限列表
// GET /api/v1/permissions
// GET /api/admin/permissions
func (h *PermissionHandler) List(c *fiber.Ctx) error {
var req dto.PermissionListRequest
if err := c.QueryParser(&req); err != nil {
@@ -107,7 +107,7 @@ func (h *PermissionHandler) List(c *fiber.Ctx) error {
}
// GetTree 获取权限树
// GET /api/v1/permissions/tree
// GET /api/admin/permissions/tree
func (h *PermissionHandler) GetTree(c *fiber.Ctx) error {
var availableForRoleType *int
if roleTypeStr := c.Query("available_for_role_type"); roleTypeStr != "" {

48
internal/handler/admin/role.go
View File

@@ -5,8 +5,10 @@ import (
"github.com/go-playground/validator/v10"
"github.com/gofiber/fiber/v2"
"go.uber.org/zap"
"github.com/break/junhong_cmp_fiber/pkg/errors"
"github.com/break/junhong_cmp_fiber/pkg/logger"
"github.com/break/junhong_cmp_fiber/pkg/response"
"github.com/break/junhong_cmp_fiber/internal/model/dto"
@@ -28,7 +30,7 @@ func NewRoleHandler(service *roleService.Service, validator *validator.Validate)
}
// Create 创建角色
// POST /api/v1/roles
// POST /api/admin/roles
func (h *RoleHandler) Create(c *fiber.Ctx) error {
var req dto.CreateRoleRequest
if err := c.BodyParser(&req); err != nil {
@@ -36,7 +38,12 @@ func (h *RoleHandler) Create(c *fiber.Ctx) error {
}
if err := h.validator.Struct(&req); err != nil {
return errors.New(errors.CodeInvalidParam, "参数验证失败: "+err.Error())
logger.GetAppLogger().Warn("参数验证失败",
zap.String("path", c.Path()),
zap.String("method", c.Method()),
zap.Error(err),
)
return errors.New(errors.CodeInvalidParam)
}
role, err := h.service.Create(c.UserContext(), &req)
@@ -48,7 +55,7 @@ func (h *RoleHandler) Create(c *fiber.Ctx) error {
}
// Get 获取角色详情
// GET /api/v1/roles/:id
// GET /api/admin/roles/:id
func (h *RoleHandler) Get(c *fiber.Ctx) error {
id, err := strconv.ParseUint(c.Params("id"), 10, 64)
if err != nil {
@@ -64,7 +71,7 @@ func (h *RoleHandler) Get(c *fiber.Ctx) error {
}
// Update 更新角色
// PUT /api/v1/roles/:id
// PUT /api/admin/roles/:id
func (h *RoleHandler) Update(c *fiber.Ctx) error {
id, err := strconv.ParseUint(c.Params("id"), 10, 64)
if err != nil {
@@ -77,7 +84,12 @@ func (h *RoleHandler) Update(c *fiber.Ctx) error {
}
if err := h.validator.Struct(&req); err != nil {
return errors.New(errors.CodeInvalidParam, "参数验证失败: "+err.Error())
logger.GetAppLogger().Warn("参数验证失败",
zap.String("path", c.Path()),
zap.String("method", c.Method()),
zap.Error(err),
)
return errors.New(errors.CodeInvalidParam)
}
role, err := h.service.Update(c.UserContext(), uint(id), &req)
@@ -89,7 +101,7 @@ func (h *RoleHandler) Update(c *fiber.Ctx) error {
}
// Delete 删除角色
// DELETE /api/v1/roles/:id
// DELETE /api/admin/roles/:id
func (h *RoleHandler) Delete(c *fiber.Ctx) error {
id, err := strconv.ParseUint(c.Params("id"), 10, 64)
if err != nil {
@@ -104,7 +116,7 @@ func (h *RoleHandler) Delete(c *fiber.Ctx) error {
}
// List 查询角色列表
// GET /api/v1/roles
// GET /api/admin/roles
func (h *RoleHandler) List(c *fiber.Ctx) error {
var req dto.RoleListRequest
if err := c.QueryParser(&req); err != nil {
@@ -120,7 +132,7 @@ func (h *RoleHandler) List(c *fiber.Ctx) error {
}
// AssignPermissions 为角色分配权限
// POST /api/v1/roles/:id/permissions
// POST /api/admin/roles/:id/permissions
func (h *RoleHandler) AssignPermissions(c *fiber.Ctx) error {
id, err := strconv.ParseUint(c.Params("id"), 10, 64)
if err != nil {
@@ -133,7 +145,12 @@ func (h *RoleHandler) AssignPermissions(c *fiber.Ctx) error {
}
if err := h.validator.Struct(&req); err != nil {
return errors.New(errors.CodeInvalidParam, "参数验证失败: "+err.Error())
logger.GetAppLogger().Warn("参数验证失败",
zap.String("path", c.Path()),
zap.String("method", c.Method()),
zap.Error(err),
)
return errors.New(errors.CodeInvalidParam)
}
rps, err := h.service.AssignPermissions(c.UserContext(), uint(id), req.PermIDs)
@@ -145,7 +162,7 @@ func (h *RoleHandler) AssignPermissions(c *fiber.Ctx) error {
}
// GetPermissions 获取角色的所有权限
// GET /api/v1/roles/:id/permissions
// GET /api/admin/roles/:id/permissions
func (h *RoleHandler) GetPermissions(c *fiber.Ctx) error {
id, err := strconv.ParseUint(c.Params("id"), 10, 64)
if err != nil {
@@ -161,7 +178,7 @@ func (h *RoleHandler) GetPermissions(c *fiber.Ctx) error {
}
// RemovePermission 移除角色的权限
// DELETE /api/v1/roles/:role_id/permissions/:perm_id
// DELETE /api/admin/roles/:role_id/permissions/:perm_id
func (h *RoleHandler) RemovePermission(c *fiber.Ctx) error {
roleID, err := strconv.ParseUint(c.Params("role_id"), 10, 64)
if err != nil {
@@ -181,7 +198,7 @@ func (h *RoleHandler) RemovePermission(c *fiber.Ctx) error {
}
// UpdateStatus 更新角色状态
// PUT /api/v1/roles/:id/status
// PUT /api/admin/roles/:id/status
func (h *RoleHandler) UpdateStatus(c *fiber.Ctx) error {
id, err := strconv.ParseUint(c.Params("id"), 10, 64)
if err != nil {
@@ -194,7 +211,12 @@ func (h *RoleHandler) UpdateStatus(c *fiber.Ctx) error {
}
if err := h.validator.Struct(&req); err != nil {
return errors.New(errors.CodeInvalidParam, "参数验证失败: "+err.Error())
logger.GetAppLogger().Warn("参数验证失败",
zap.String("path", c.Path()),
zap.String("method", c.Method()),
zap.Error(err),
)
return errors.New(errors.CodeInvalidParam)
}
if err := h.service.UpdateStatus(c.UserContext(), uint(id), req.Status); err != nil {

11
internal/handler/admin/storage.go
View File

@@ -2,9 +2,11 @@ package admin
import (
"github.com/gofiber/fiber/v2"
"go.uber.org/zap"
"github.com/break/junhong_cmp_fiber/internal/model/dto"
"github.com/break/junhong_cmp_fiber/pkg/errors"
"github.com/break/junhong_cmp_fiber/pkg/logger"
"github.com/break/junhong_cmp_fiber/pkg/response"
"github.com/break/junhong_cmp_fiber/pkg/storage"
)
@@ -29,7 +31,14 @@ func (h *StorageHandler) GetUploadURL(c *fiber.Ctx) error {
result, err := h.service.GetUploadURL(c.UserContext(), req.Purpose, req.FileName, req.ContentType)
if err != nil {
return errors.New(errors.CodeInternalError, err.Error())
logger.GetAppLogger().Error("获取上传URL失败",
zap.String("path", c.Path()),
zap.String("method", c.Method()),
zap.String("purpose", req.Purpose),
zap.String("fileName", req.FileName),
zap.Error(err),
)
return errors.New(errors.CodeInternalError, "获取上传URL失败")
}
return response.Success(c, dto.GetUploadURLResponse{

216
internal/handler/admin/task.go
View File

@@ -1,216 +0,0 @@
package admin
import (
"fmt"
"time"
"github.com/go-playground/validator/v10"
"github.com/gofiber/fiber/v2"
"github.com/google/uuid"
"github.com/hibiken/asynq"
"go.uber.org/zap"
"github.com/break/junhong_cmp_fiber/internal/task"
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/break/junhong_cmp_fiber/pkg/errors"
"github.com/break/junhong_cmp_fiber/pkg/queue"
"github.com/break/junhong_cmp_fiber/pkg/response"
)
// TaskHandler 任务处理器
type TaskHandler struct {
queueClient *queue.Client
logger *zap.Logger
validator *validator.Validate
}
// NewTaskHandler 创建任务处理器实例
func NewTaskHandler(queueClient *queue.Client, logger *zap.Logger) *TaskHandler {
return &TaskHandler{
queueClient: queueClient,
logger: logger,
validator: validator.New(),
}
}
// SubmitEmailTaskRequest 提交邮件任务请求
type SubmitEmailTaskRequest struct {
To string `json:"to" validate:"required,email"`
Subject string `json:"subject" validate:"required,min=1,max=200"`
Body string `json:"body" validate:"required,min=1"`
CC []string `json:"cc,omitempty" validate:"omitempty,dive,email"`
Attachments []string `json:"attachments,omitempty"`
RequestID string `json:"request_id,omitempty"`
}
// SubmitSyncTaskRequest 提交数据同步任务请求
type SubmitSyncTaskRequest struct {
SyncType string `json:"sync_type" validate:"required,oneof=sim_status flow_usage real_name"`
StartDate string `json:"start_date" validate:"required"`
EndDate string `json:"end_date" validate:"required"`
BatchSize int `json:"batch_size,omitempty" validate:"omitempty,min=1,max=1000"`
RequestID string `json:"request_id,omitempty"`
Priority string `json:"priority,omitempty" validate:"omitempty,oneof=critical default low"`
}
// TaskResponse 任务响应
type TaskResponse struct {
TaskID string `json:"task_id"`
Queue string `json:"queue"`
Status string `json:"status"`
}
// SubmitEmailTask 提交邮件发送任务
// @Summary 提交邮件发送任务
// @Description 异步发送邮件
// @Tags 任务
// @Accept json
// @Produce json
// @Param request body SubmitEmailTaskRequest true "邮件任务参数"
// @Success 200 {object} response.Response{data=TaskResponse}
// @Failure 400 {object} response.Response
// @Router /api/v1/tasks/email [post]
func (h *TaskHandler) SubmitEmailTask(c *fiber.Ctx) error {
var req SubmitEmailTaskRequest
if err := c.BodyParser(&req); err != nil {
h.logger.Warn("解析邮件任务请求失败",
zap.Error(err))
return errors.New(errors.CodeInvalidParam, "请求参数格式错误")
}
// 验证参数
if err := h.validator.Struct(&req); err != nil {
h.logger.Warn("邮件任务参数验证失败",
zap.Error(err))
return errors.New(errors.CodeInvalidParam, err.Error())
}
// 生成 RequestID（如果未提供）
if req.RequestID == "" {
req.RequestID = generateRequestID("email")
}
// 构造任务载荷
payload := &task.EmailPayload{
RequestID: req.RequestID,
To: req.To,
Subject: req.Subject,
Body: req.Body,
CC: req.CC,
Attachments: req.Attachments,
}
// 提交任务到队列
err := h.queueClient.EnqueueTask(
c.Context(),
constants.TaskTypeEmailSend,
payload,
asynq.Queue(constants.QueueDefault),
asynq.MaxRetry(constants.DefaultRetryMax),
asynq.Timeout(constants.DefaultTimeout),
)
if err != nil {
h.logger.Error("提交邮件任务失败",
zap.String("to", req.To),
zap.String("request_id", req.RequestID),
zap.Error(err))
return errors.New(errors.CodeInternalError, "任务提交失败")
}
h.logger.Info("邮件任务提交成功",
zap.String("queue", constants.QueueDefault),
zap.String("to", req.To),
zap.String("request_id", req.RequestID))
return response.SuccessWithMessage(c, TaskResponse{
TaskID: req.RequestID,
Queue: constants.QueueDefault,
Status: "queued",
}, "邮件任务已提交")
}
// SubmitSyncTask 提交数据同步任务
// @Summary 提交数据同步任务
// @Description 异步执行数据同步
// @Tags 任务
// @Accept json
// @Produce json
// @Param request body SubmitSyncTaskRequest true "同步任务参数"
// @Success 200 {object} response.Response{data=TaskResponse}
// @Failure 400 {object} response.Response
// @Router /api/v1/tasks/sync [post]
func (h *TaskHandler) SubmitSyncTask(c *fiber.Ctx) error {
var req SubmitSyncTaskRequest
if err := c.BodyParser(&req); err != nil {
h.logger.Warn("解析同步任务请求失败",
zap.Error(err))
return errors.New(errors.CodeInvalidParam, "请求参数格式错误")
}
// 验证参数
if err := h.validator.Struct(&req); err != nil {
h.logger.Warn("同步任务参数验证失败",
zap.Error(err))
return errors.New(errors.CodeInvalidParam, err.Error())
}
// 生成 RequestID（如果未提供）
if req.RequestID == "" {
req.RequestID = generateRequestID("sync")
}
// 设置默认批量大小
if req.BatchSize == 0 {
req.BatchSize = 100
}
// 确定队列优先级
queueName := constants.QueueDefault
if req.Priority == "critical" {
queueName = constants.QueueCritical
} else if req.Priority == "low" {
queueName = constants.QueueLow
}
// 构造任务载荷
payload := &task.DataSyncPayload{
RequestID: req.RequestID,
SyncType: req.SyncType,
StartDate: req.StartDate,
EndDate: req.EndDate,
BatchSize: req.BatchSize,
}
// 提交任务到队列
err := h.queueClient.EnqueueTask(
c.Context(),
constants.TaskTypeDataSync,
payload,
asynq.Queue(queueName),
asynq.MaxRetry(constants.DefaultRetryMax),
asynq.Timeout(constants.DefaultTimeout),
)
if err != nil {
h.logger.Error("提交同步任务失败",
zap.String("sync_type", req.SyncType),
zap.String("request_id", req.RequestID),
zap.Error(err))
return errors.New(errors.CodeInternalError, "任务提交失败")
}
h.logger.Info("同步任务提交成功",
zap.String("queue", queueName),
zap.String("sync_type", req.SyncType),
zap.String("request_id", req.RequestID))
return response.SuccessWithMessage(c, TaskResponse{
TaskID: req.RequestID,
Queue: queueName,
Status: "queued",
}, "同步任务已提交")
}
// generateRequestID 生成请求 ID
func generateRequestID(prefix string) string {
return fmt.Sprintf("%s-%s-%d", prefix, uuid.New().String(), time.Now().UnixNano())
}