license-manager/backend/docs/api_development_guide.md

API 开发规范

核心要点

一定要阅读customer模块的实现，看看其他模块的实，明白编码细节，现然后再进行开发。

1. 分层架构

internal/
├── models/          # 数据模型：结构体定义、验证规则
├── service/         # 业务逻辑：核心业务规则实现
├── repository/      # 数据访问：数据库、缓存操作
└── api/handlers/    # HTTP处理：请求处理、响应格式化

职责边界：

• Models：数据结构、输入验证、响应格式
• Service：业务规则、数据处理、跨模块协调
• Repository：数据持久化、查询优化、事务管理
• Handler：HTTP协议、参数绑定、错误响应

2. 多语言支持

枚举字段扩展：为所有枚举类型添加*_display字段

{
  "status": "active",
  "status_display": "激活",
  "customer_type": "enterprise", 
  "customer_type_display": "企业客户"
}

语言检测优先级：

1. URL参数：?lang=en-US
2. HTTP Header：Accept-Language
3. 系统默认：配置文件指定

3. 错误处理

错误码规范：六位数字

• 前2位：模块代码（10=认证，20=客户，30=授权，90=系统）
• 后4位：连续错误号

统一响应格式：

{
  "code": 0,
  "message": "success",
  "data": {...}
}

4. RESTful设计

路由规范：

• 使用名词表示资源
• HTTP方法体现操作
• 版本控制：/api/v1/

HTTP状态码：

• 200：成功（包括业务逻辑失败）
• 400：请求格式错误
• 401：身份认证失败
• 403：权限不足
• 500：服务器内部错误

5. 开发流程

1. 定义模型结构（含多语言字段）
2. 声明服务接口
3. 实现业务逻辑（添加i18n处理）
4. 编写HTTP处理器
5. 注册路由
6. 完善Swagger文档

6. 质量检查

• 分层职责是否清晰
• 多语言字段是否完整
• 错误处理是否统一
• Swagger注解是否完整
• 避免不必要的冗余，能写到工具函数的不要写在模块内