@stackonward/cli 0.0.1 → 1.0.1

package/dist/resources/templates/go-backend/.claude/docs/api-design.md

@@ -0,0 +1,486 @@
+# API Design Templates
+
+> Templates only. Rules are in `CLAUDE.md`.
+
+## OpenAPI Security Contract
+
+Protected applications declare security on every canonical OpenAPI operation. The service source defines reusable security schemes, while each operation uses either a non-empty Security Requirement Object or an explicit empty array for anonymous access.
+
+Rules:
+
+1. Never rely on root-level security to conceal an operation-level omission.
+2. Public audience and anonymous access are separate decisions.
+3. Admin and internal operations use their actual IAM or service credential scheme.
+4. The Gin middleware chain and OpenAPI security declaration must describe the same boundary.
+5. Security changes participate in `make openapi-breaking`.
+
+---
+
+## Handler
+
+```go
+// internal/platform/user/handler.go
+
+// UserHandler 用户 HTTP 接口
+type UserHandler struct {
+	svc    *application.UserService
+	logger *zap.Logger
+}
+
+// NewUserHandler 创建用户 Handler
+func NewUserHandler(svc *application.UserService, logger *zap.Logger) *UserHandler {
+	return &UserHandler{svc: svc, logger: logger.Named("UserHandler")}
+}
+
+// RegisterRoutes 注册路由到 Gin RouterGroup
+func (h *UserHandler) RegisterRoutes(rg *gin.RouterGroup) {
+	users := rg.Group("/users")
+	{
+		users.POST("", h.Create)
+		users.GET("", h.List)
+		users.GET("/:id", h.GetByID)
+		users.PATCH("/:id", h.Update)
+		users.DELETE("/:id", h.Delete)
+	}
+}
+
+// Create 创建用户
+func (h *UserHandler) Create(c *gin.Context) {
+	var req application.CreateUserRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.ValidationError(c, err)
+		return
+	}
+	result, err := h.svc.Create(c.Request.Context(), &req)
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	response.Created(c, result)
+}
+
+// List 用户列表
+func (h *UserHandler) List(c *gin.Context) {
+	var query application.UserQueryRequest
+	if err := c.ShouldBindQuery(&query); err != nil {
+		response.ValidationError(c, err)
+		return
+	}
+	result, err := h.svc.List(c.Request.Context(), &query)
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	response.OK(c, result)
+}
+
+// GetByID 根据 ID 获取用户
+func (h *UserHandler) GetByID(c *gin.Context) {
+	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.Error(c, apierror.BadRequest("invalid_parameters", "Invalid user ID"))
+		return
+	}
+	result, err := h.svc.GetByID(c.Request.Context(), id)
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	response.OK(c, result)
+}
+
+// Update 更新用户
+func (h *UserHandler) Update(c *gin.Context) {
+	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.Error(c, apierror.BadRequest("invalid_parameters", "Invalid user ID"))
+		return
+	}
+	var req application.UpdateUserRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.ValidationError(c, err)
+		return
+	}
+	result, err := h.svc.Update(c.Request.Context(), id, &req)
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	response.OK(c, result)
+}
+
+// Delete 删除用户
+func (h *UserHandler) Delete(c *gin.Context) {
+	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.Error(c, apierror.BadRequest("invalid_parameters", "Invalid user ID"))
+		return
+	}
+	if err := h.svc.Delete(c.Request.Context(), id); err != nil {
+		response.Error(c, err)
+		return
+	}
+	response.NoContent(c)
+}
+```
+
+## Service
+
+```go
+// internal/platform/user/application/service.go
+
+// UserService 用户业务逻辑
+type UserService struct {
+	repo   domain.UserRepository
+	events *eventbus.EventBus
+	logger *zap.Logger
+}
+
+// NewUserService 创建 UserService
+func NewUserService(repo domain.UserRepository, events *eventbus.EventBus, logger *zap.Logger) *UserService {
+	return &UserService{repo: repo, events: events, logger: logger.Named("UserService")}
+}
+
+func (s *UserService) Create(ctx context.Context, req *CreateUserRequest) (*UserResponse, error) {
+	user := &domain.User{
+		Name:  req.Name,
+		Email: req.Email,
+		Role:  req.Role,
+	}
+	if err := s.repo.Create(ctx, user); err != nil {
+		return nil, fmt.Errorf("create user: %w", err)
+	}
+	s.logger.Info("user created", zap.Int64("userId", user.ID))
+
+	// L3 审计：记录创建结果
+	audit.Enrich(ctx, &audit.ChangesPayload{
+		After: map[string]any{"id": user.ID, "name": user.Name, "email": user.Email},
+	}, nil)
+
+	return ToUserResponse(user), nil
+}
+
+func (s *UserService) List(ctx context.Context, query *UserQueryRequest) (response.Paginated[UserResponse], error) {
+	query.Normalize()
+	page, pageSize := query.Page, query.PageSize
+	users, total, err := s.repo.FindAll(ctx, domain.UserFilter{
+		Status: query.Status,
+	}, page, pageSize)
+	if err != nil {
+		return response.Paginated[UserResponse]{}, fmt.Errorf("list users: %w", err)
+	}
+	items := make([]UserResponse, 0, len(users))
+	for i := range users {
+		items = append(items, *ToUserResponse(&users[i]))
+	}
+	return response.NewPaginated(items, page, pageSize, total), nil
+}
+
+func (s *UserService) GetByID(ctx context.Context, id int64) (*UserResponse, error) {
+	user, err := s.repo.FindByID(ctx, id)
+	if err != nil {
+		return nil, fmt.Errorf("get user: %w", err)
+	}
+	if user == nil {
+		return nil, apierror.NotFound("User", id)
+	}
+	return ToUserResponse(user), nil
+}
+
+func (s *UserService) Update(ctx context.Context, id int64, req *UpdateUserRequest) (*UserResponse, error) {
+	user, err := s.repo.FindByID(ctx, id)
+	if err != nil {
+		return nil, fmt.Errorf("get user for update: %w", err)
+	}
+	if user == nil {
+		return nil, apierror.NotFound("User", id)
+	}
+
+	// 审计快照：记录变更前状态
+	before := map[string]any{"name": user.Name, "email": user.Email}
+
+	if req.Name != nil {
+		user.Name = *req.Name
+	}
+	if req.Email != nil {
+		user.Email = *req.Email
+	}
+	if err := s.repo.Update(ctx, user); err != nil {
+		return nil, fmt.Errorf("update user: %w", err)
+	}
+
+	// L3 审计：记录变更前后
+	audit.Enrich(ctx, &audit.ChangesPayload{
+		Before: before,
+		After:  map[string]any{"name": user.Name, "email": user.Email},
+	}, nil)
+
+	return ToUserResponse(user), nil
+}
+
+func (s *UserService) Delete(ctx context.Context, id int64) error {
+	user, err := s.repo.FindByID(ctx, id)
+	if err != nil {
+		return fmt.Errorf("get user for delete: %w", err)
+	}
+	if user == nil {
+		return apierror.NotFound("User", id)
+	}
+	if err := s.repo.SoftDelete(ctx, id); err != nil {
+		return fmt.Errorf("soft delete user: %w", err)
+	}
+
+	// L3 审计：记录删除前状态
+	audit.Enrich(ctx, &audit.ChangesPayload{
+		Before: map[string]any{"id": user.ID, "name": user.Name},
+	}, nil)
+
+	return nil
+}
+```
+
+## DTO (Request)
+
+```go
+// internal/platform/user/application/dto.go
+
+// CreateUserRequest 创建用户请求
+type CreateUserRequest struct {
+	// 显示名称
+	Name string `json:"name" binding:"required,max=100"`
+	// 邮箱地址
+	Email string `json:"email" binding:"required,email"`
+	// 用户角色
+	Role string `json:"role" binding:"required,oneof=admin member guest"`
+}
+
+// UpdateUserRequest 更新用户请求
+type UpdateUserRequest struct {
+	// 显示名称
+	Name *string `json:"name,omitempty" binding:"omitempty,max=100"`
+	// 邮箱地址
+	Email *string `json:"email,omitempty" binding:"omitempty,email"`
+	// 用户角色
+	Role *string `json:"role,omitempty" binding:"omitempty,oneof=admin member guest"`
+}
+
+// UserQueryRequest 用户查询请求
+type UserQueryRequest struct {
+	// 状态筛选
+	Status *string `form:"status" binding:"omitempty,oneof=active suspended deleted"`
+	types.PageParams
+}
+```
+
+## VO (Response) + Transform
+
+```go
+// internal/platform/user/application/vo.go
+
+// UserResponse 用户响应
+type UserResponse struct {
+	ID        int64     `json:"id"`
+	Name      string    `json:"name"`
+	Email     string    `json:"email"`
+	Role      string    `json:"role"`
+	CreatedAt time.Time `json:"created_at"`
+}
+
+// ToUserResponse Model -> Response 转换
+func ToUserResponse(user *domain.User) *UserResponse {
+	return &UserResponse{
+		ID:        user.ID,
+		Name:      user.Name,
+		Email:     user.Email,
+		Role:      user.Role,
+		CreatedAt: user.CreatedAt,
+	}
+}
+```
+
+## Pagination Types
+
+```go
+package response
+
+// PaginationMeta 分页元数据
+type PaginationMeta struct {
+	// 当前页码
+	Page int `json:"page"`
+	// 每页条数
+	PageSize int `json:"page_size"`
+	// 总记录数
+	Total int64 `json:"total"`
+	// 总页数
+	TotalPages int `json:"total_pages"`
+}
+
+// Paginated 分页响应泛型结构体
+type Paginated[T any] struct {
+	// 数据列表
+	Data []T `json:"data"`
+	// 分页信息
+	Pagination PaginationMeta `json:"pagination"`
+}
+
+// NewList 创建无分页的列表响应，保持与分页接口相同的 { data, pagination } 契约
+func NewList[T any](data []T) Paginated[T] {
+	if data == nil {
+		data = make([]T, 0)
+	}
+	count := len(data)
+	return Paginated[T]{
+		Data: data,
+		Pagination: PaginationMeta{
+			Page:       1,
+			PageSize:   count,
+			Total:      int64(count),
+			TotalPages: 1,
+		},
+	}
+}
+
+// NewPaginated 创建分页响应
+func NewPaginated[T any](data []T, page, pageSize int, total int64) Paginated[T] {
+	totalPages := 0
+	if pageSize > 0 {
+		totalPages = int((total + int64(pageSize) - 1) / int64(pageSize))
+	}
+
+	if data == nil {
+		data = make([]T, 0)
+	}
+
+	return Paginated[T]{
+		Data: data,
+		Pagination: PaginationMeta{
+			Page:       page,
+			PageSize:   pageSize,
+			Total:      total,
+			TotalPages: totalPages,
+		},
+	}
+}
+```
+
+## Response Helpers
+
+```go
+package response
+
+import (
+	"errors"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	"github.com/go-playground/validator/v10"
+
+	"{{module}}/internal/common/types"
+	"{{module}}/pkg/apierror"
+)
+
+// OK 200 成功响应
+func OK(c *gin.Context, data any) {
+	c.JSON(http.StatusOK, data)
+}
+
+// Created 201 创建成功响应
+func Created(c *gin.Context, data any) {
+	c.JSON(http.StatusCreated, data)
+}
+
+// Accepted 202 异步任务已接受响应
+func Accepted(c *gin.Context, data any) {
+	c.JSON(http.StatusAccepted, data)
+}
+
+// NoContent 204 无内容响应
+func NoContent(c *gin.Context) {
+	c.Status(http.StatusNoContent)
+}
+
+// Error 根据 error 类型自动选择状态码和响应格式
+func Error(c *gin.Context, err error) {
+	var httpErr apierror.HTTPError
+	if errors.As(err, &httpErr) {
+		status := httpErr.HTTPStatus()
+		// 410 Gone 响应附加 noindex 头，通知搜索引擎不再索引
+		if status == http.StatusGone {
+			c.Header("X-Robots-Tag", "noindex, nofollow")
+		}
+		if status == http.StatusTooManyRequests || status == http.StatusServiceUnavailable {
+			if retryAfter := httpErr.HTTPResponseMetadata().RetryAfter(); retryAfter != "" {
+				c.Header(types.HeaderRetryAfter, retryAfter)
+			}
+		}
+		c.JSON(status, httpErr.ToResponse())
+		return
+	}
+
+	// 未知错误：注入 Gin context 供 logging middleware 输出错误详情，返回通用 500
+	_ = c.Error(err)
+	internal := apierror.Internal("Internal server error")
+	c.JSON(internal.Status, internal.ToResponse())
+}
+
+// ValidationError 格式化 go-playground/validator 的校验错误
+func ValidationError(c *gin.Context, err error) {
+	var ve validator.ValidationErrors
+	if !errors.As(err, &ve) {
+		// 非 validator 校验错误，按普通错误处理
+		apiErr := apierror.BadRequest(apierror.CodeValidationFailed, err.Error())
+		c.JSON(apiErr.Status, apiErr.ToResponse())
+		return
+	}
+
+	fieldErrors := make([]apierror.FieldError, 0, len(ve))
+	for _, fe := range ve {
+		fieldErrors = append(fieldErrors, apierror.FieldError{
+			Field:   fe.Field(),
+			Message: formatValidationMessage(fe),
+		})
+	}
+
+	apiErr := apierror.ValidationFailed(fieldErrors)
+	c.JSON(apiErr.Status, apiErr.ToResponse())
+}
+
+// formatValidationMessage 将 validator tag 转换为可读的错误消息
+func formatValidationMessage(fe validator.FieldError) string {
+	switch fe.Tag() {
+	case "required":
+		return "is required"
+	case "email":
+		return "must be a valid email"
+	case "min":
+		return "must be at least " + fe.Param()
+	case "max":
+		return "must be at most " + fe.Param()
+	case "len":
+		return "must have length " + fe.Param()
+	case "oneof":
+		return "must be one of: " + fe.Param()
+	case "uuid":
+		return "must be a valid UUID"
+	case "url":
+		return "must be a valid URL"
+	case "gte":
+		return "must be greater than or equal to " + fe.Param()
+	case "lte":
+		return "must be less than or equal to " + fe.Param()
+	case "gt":
+		return "must be greater than " + fe.Param()
+	case "lt":
+		return "must be less than " + fe.Param()
+	default:
+		return "failed on " + fe.Tag() + " validation"
+	}
+}
+```
+
+## Error Response Format
+
+```json
+{ "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "User with id 123 not found" } }
+{ "error": { "type": "validation_error", "code": "invalid_parameters", "message": "Request validation failed", "errors": [{ "field": "email", "message": "must be a valid email" }] } }
+```