restful api设计需遵循http方法语义、名词化资源路径、url版本控制及标准状态码；采用handler-service-repository-domain四层架构分离关注点；工程化要求配置管理、统一错误处理、可观测性与多层测试覆盖。
restful api设计需遵循http方法语义、名词化资源路径、url版本控制及标准状态码；采用handler-service-repository-domain四层架构分离关注点；工程化要求配置管理、统一错误处理、可观测性与多层测试覆盖。
RESTful API 的核心设计原则
用标准 HTTP 方法表达资源操作：GET 获取、POST 创建、PUT/PATCH 更新、DELETE 删除。资源路径要名词化，比如 /api/v1/users 而不是 /api/v1/getUsers；版本号放在 URL 路径中（如 v1），便于后续兼容升级；状态码严格遵循语义，200/201 表示成功，400 处理客户端错误，404 找不到资源，500 服务端异常。
分层架构：清晰分离关注点
推荐采用四层结构，避免业务逻辑散落在 handler 中：
- Handler 层：只做请求解析（绑定参数、校验）、响应封装（统一格式、状态码），不碰数据库或业务规则
- Service 层：实现核心业务逻辑，比如“创建用户需检查邮箱唯一性 + 发送欢迎邮件”，可被多个 handler 复用
- Repository 层：封装数据访问，对接数据库（如 GORM）或外部服务，返回 domain 模型，不暴露 SQL 或 driver 细节
-
Domain 层：定义纯 Go 结构体（如
User），含字段和基础方法（如IsValidEmail()），不含框架依赖
关键代码片段（基于 Gin + GORM）
路由与中间件：
注册带版本前缀的路由组，统一挂载日志、CORS、JWT 验证中间件：
立即学习“go语言免费学习笔记（深入）”；
r := gin.Default()
v1 := r.Group("/api/v1")
v1.Use(middleware.Logger(), middleware.CORSMiddleware(), auth.JWTAuth())
{
v1.GET("/users", userHandler.List)
v1.POST("/users", userHandler.Create)
v1.GET("/users/:id", userHandler.Get)
v1.PUT("/users/:id", userHandler.Update)
}Handler 示例（精简）：
只负责“转接”，把请求数据交给 service，再把结果转成 JSON：
func (h *UserHandler) Create(c *gin.Context) {
var req CreateUserRequest
if err := c.ShouldBindJSON(&req); err != nil {
c.JSON(http.StatusBadRequest, gin.H{"error": "invalid request"})
return
}
user, err := h.userService.Create(c.Request.Context(), req.ToDomain())
if err != nil {
c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
return
}
c.JSON(http.StatusCreated, user)
}统一响应格式：
所有接口返回结构一致，前端无需重复判断字段：
type Response struct {
Code int `json:"code"`
Message string `json:"message"`
Data interface{} `json:"data,omitempty"`
}
// 使用：c.JSON(200, Response{Code: 200, Message: "ok", Data: user})工程化要点（上线必备）
配置管理：用 spf13/viper 加载 YAML 配置，区分开发/测试/生产环境，敏感信息（DB 密码、JWT 秘钥）从环境变量注入。
错误处理：定义业务错误码（如 ErrUserNotFound = errors.New("user not found")），在 middleware 中统一映射为 HTTP 状态码和提示文案。
可观测性：集成 uber-go/zap 日志（带 traceID）、prometheus/client_golang 暴露 QPS/延迟指标、用 go.opentelemetry.io/otel 做链路追踪。
测试覆盖：handler 层用 Gin 的 httptest 写集成测试；service 层用纯 Go 单元测试（mock repository）；关键路径（如登录、支付）加端到端测试。
