# API参考

<cite>
**本文引用的文件**
- [routes.go](file://internal/handler/routes.go)
- [swagger.go](file://internal/handler/swagger.go)
- [auth_handler.go](file://internal/handler/auth_handler.go)
- [user_handler.go](file://internal/handler/user_handler.go)
- [texture_handler.go](file://internal/handler/texture_handler.go)
- [profile_handler.go](file://internal/handler/profile_handler.go)
- [captcha_handler.go](file://internal/handler/captcha_handler.go)
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go)
- [auth.go](file://internal/middleware/auth.go)
- [response.go](file://internal/model/response.go)
- [common.go](file://internal/types/common.go)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本API参考面向CarrotSkin后端服务，覆盖认证、用户、材质、档案、验证码、Yggdrasil与系统配置等API组。文档基于routes.go与swagger.go中的路由与注释，结合各处理器文件的注释与类型定义，提供：
- 端点清单与HTTP方法、URL模式
- 请求/响应模式与鉴权要求（JWT）
- 错误码与常见错误场景
- 参数校验规则与示例
- 性能优化建议与最佳实践

## 项目结构
- 路由注册集中在路由文件，按版本分组与鉴权中间件组合
- Swagger文档与健康检查在统一入口启用
- 各功能模块处理器文件通过注释提供OpenAPI规范
- 中间件负责JWT鉴权与可选鉴权
- 响应模型与类型定义集中于model与types目录

```mermaid
graph TB
A["Gin引擎"] --> B["Swagger文档<br/>/swagger/*any"]
A --> C["健康检查<br/>/health"]
A --> D["API v1 组<br/>/api/v1"]
D --> E["认证组<br/>/api/v1/auth/*"]
D --> F["用户组<br/>/api/v1/user/*"]
D --> G["材质组<br/>/api/v1/texture/*"]
D --> H["档案组<br/>/api/v1/profile/*"]
D --> I["验证码组<br/>/api/v1/captcha/*"]
D --> J["Yggdrasil组<br/>/api/v1/yggdrasil/*"]
D --> K["系统组<br/>/api/v1/system/*"]
```

图表来源
- [routes.go](file://internal/handler/routes.go#L10-L118)
- [swagger.go](file://internal/handler/swagger.go#L41-L63)

章节来源
- [routes.go](file://internal/handler/routes.go#L10-L118)
- [swagger.go](file://internal/handler/swagger.go#L41-L63)

## 核心组件
- 路由注册器：按版本分组，按需挂载鉴权中间件
- Swagger：提供交互式文档与健康检查
- 鉴权中间件：统一从Authorization头解析Bearer Token并注入用户上下文
- 响应模型：统一的响应结构与分页结构
- 类型定义：请求/响应结构体与约束规则

章节来源
- [routes.go](file://internal/handler/routes.go#L10-L118)
- [swagger.go](file://internal/handler/swagger.go#L41-L63)
- [auth.go](file://internal/middleware/auth.go#L12-L56)
- [response.go](file://internal/model/response.go#L1-L86)
- [common.go](file://internal/types/common.go#L1-L215)

## 架构总览
下图展示API调用链与鉴权流程：

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Router as "Gin路由"
participant MW as "鉴权中间件"
participant Handler as "处理器"
participant Service as "服务层"
participant DB as "数据库/缓存"
Client->>Router : "HTTP请求"
Router->>MW : "匹配路由并执行中间件"
MW->>MW : "解析Authorization头"
MW->>MW : "校验JWT并注入用户上下文"
MW-->>Router : "通过或拒绝"
Router->>Handler : "转发到对应处理器"
Handler->>Service : "调用业务逻辑"
Service->>DB : "读写数据"
DB-->>Service : "返回结果"
Service-->>Handler : "返回业务结果"
Handler-->>Client : "统一响应结构"
```

图表来源
- [auth.go](file://internal/middleware/auth.go#L12-L56)
- [routes.go](file://internal/handler/routes.go#L10-L118)

## 详细组件分析

### 认证组（/api/v1/auth）
- 无需JWT
- 端点
  - POST /api/v1/auth/register
    - 请求体：RegisterRequest
    - 响应：LoginResponse（含token与用户信息）
    - 错误：400（参数错误）、401（登录失败）
  - POST /api/v1/auth/login
    - 请求体：LoginRequest（支持用户名或邮箱）
    - 响应：LoginResponse
    - 错误：400（参数错误）、401（登录失败）
  - POST /api/v1/auth/send-code
    - 请求体：SendVerificationCodeRequest（类型枚举：register/reset_password/change_email）
    - 响应：通用成功响应
    - 错误：400（参数错误）
  - POST /api/v1/auth/reset-password
    - 请求体：ResetPasswordRequest（验证码6位）
    - 响应：通用成功响应
    - 错误：400（参数错误）

参数与校验要点
- RegisterRequest：用户名、邮箱、密码、验证码、可选头像URL
- LoginRequest：用户名或邮箱、密码
- SendVerificationCodeRequest：邮箱、类型
- ResetPasswordRequest：邮箱、验证码、新密码

章节来源
- [routes.go](file://internal/handler/routes.go#L18-L25)
- [auth_handler.go](file://internal/handler/auth_handler.go#L17-L84)
- [auth_handler.go](file://internal/handler/auth_handler.go#L86-L147)
- [auth_handler.go](file://internal/handler/auth_handler.go#L149-L192)
- [auth_handler.go](file://internal/handler/auth_handler.go#L194-L249)
- [common.go](file://internal/types/common.go#L27-L66)

### 用户组（/api/v1/user，需JWT）
- GET /api/v1/user/profile
  - 响应：UserInfo
  - 错误：401（未授权）、404（用户不存在）
- PUT /api/v1/user/profile
  - 请求体：UpdateUserRequest（修改密码需同时提供旧密码与新密码）
  - 响应：UserInfo
  - 错误：400（参数错误）、401（未授权）、404（用户不存在）、500（服务器错误）
- POST /api/v1/user/avatar/upload-url
  - 请求体：GenerateAvatarUploadURLRequest（文件名）
  - 响应：GenerateAvatarUploadURLResponse（含post_url、form_data、avatar_url、expires_in）
  - 错误：400（参数错误）
- PUT /api/v1/user/avatar
  - 查询参数：avatar_url
  - 响应：UserInfo
  - 错误：400（参数错误）
- POST /api/v1/user/change-email
  - 请求体：ChangeEmailRequest（新邮箱+验证码）
  - 响应：UserInfo
  - 错误：400（参数错误）、401（未授权）

参数与校验要点
- UpdateUserRequest：头像URL、旧密码、新密码（二者需同时提供）
- GenerateAvatarUploadURLRequest：文件名必填
- ChangeEmailRequest：新邮箱、验证码

章节来源
- [routes.go](file://internal/handler/routes.go#L27-L41)
- [user_handler.go](file://internal/handler/user_handler.go#L17-L68)
- [user_handler.go](file://internal/handler/user_handler.go#L70-L193)
- [user_handler.go](file://internal/handler/user_handler.go#L195-L253)
- [user_handler.go](file://internal/handler/user_handler.go#L255-L326)
- [user_handler.go](file://internal/handler/user_handler.go#L328-L416)
- [common.go](file://internal/types/common.go#L42-L80)
- [common.go](file://internal/types/common.go#L107-L125)
- [common.go](file://internal/types/common.go#L167-L179)

### 材质组（/api/v1/texture）
- 公开端点（无需JWT）
  - GET /api/v1/texture
    - 查询：keyword、type（SKIN/CAPE）、public_only、page、page_size
    - 响应：分页响应（列表项为TextureInfo）
  - GET /api/v1/texture/{id}
    - 路径参数：id
    - 响应：TextureInfo
- 需JWT端点
  - POST /api/v1/texture/upload-url
    - 请求体：GenerateTextureUploadURLRequest（文件名、纹理类型）
    - 响应：GenerateTextureUploadURLResponse（含post_url、form_data、texture_url、expires_in）
    - 错误：400（参数错误）
  - POST /api/v1/texture
    - 请求体：CreateTextureRequest（名称、描述、类型、URL、哈希、大小、公开性、是否Slim）
    - 响应：TextureInfo
    - 错误：400（参数错误）
  - PUT /api/v1/texture/{id}
    - 路径参数：id；请求体：UpdateTextureRequest（名称、描述、公开性）
    - 响应：TextureInfo
    - 错误：400（参数错误）、403（无权操作）
  - DELETE /api/v1/texture/{id}
    - 路径参数：id
    - 响应：通用成功响应
    - 错误：400（参数错误）、403（无权操作）
  - POST /api/v1/texture/{id}/favorite
    - 路径参数：id
    - 响应：布尔值（是否收藏）
    - 错误：400（参数错误）
  - GET /api/v1/texture/my
    - 查询：page、page_size
    - 响应：分页响应（列表项为TextureInfo）
  - GET /api/v1/texture/favorites
    - 查询：page、page_size
    - 响应：分页响应（列表项为TextureInfo）

参数与校验要点
- GenerateTextureUploadURLRequest：文件名必填、类型枚举（SKIN/CAPE）
- CreateTextureRequest：名称必填、URL必填且为有效URL、哈希长度64、大小>0、类型枚举
- UpdateTextureRequest：名称长度限制、公开性可选
- 搜索与分页：默认page=1、page_size默认20、最大100

章节来源
- [routes.go](file://internal/handler/routes.go#L42-L61)
- [texture_handler.go](file://internal/handler/texture_handler.go#L18-L83)
- [texture_handler.go](file://internal/handler/texture_handler.go#L85-L172)
- [texture_handler.go](file://internal/handler/texture_handler.go#L174-L223)
- [texture_handler.go](file://internal/handler/texture_handler.go#L225-L291)
- [texture_handler.go](file://internal/handler/texture_handler.go#L293-L369)
- [texture_handler.go](file://internal/handler/texture_handler.go#L371-L419)
- [texture_handler.go](file://internal/handler/texture_handler.go#L421-L471)
- [texture_handler.go](file://internal/handler/texture_handler.go#L473-L599)
- [common.go](file://internal/types/common.go#L81-L105)
- [common.go](file://internal/types/common.go#L181-L191)
- [common.go](file://internal/types/common.go#L193-L200)

### 档案组（/api/v1/profile）
- 公开端点（无需JWT）
  - GET /api/v1/profile/{uuid}
    - 路径参数：uuid
    - 响应：ProfileInfo
    - 错误：404（档案不存在）、500（服务器错误）
- 需JWT端点
  - POST /api/v1/profile
    - 请求体：CreateProfileRequest（名称）
    - 响应：ProfileInfo（含自动生成UUID）
    - 错误：400（参数错误或已达上限）、401（未授权）、500（服务器错误）
  - GET /api/v1/profile
    - 响应：ProfileInfo列表
    - 错误：401（未授权）、500（服务器错误）
  - PUT /api/v1/profile/{uuid}
    - 路径参数：uuid；请求体：UpdateProfileRequest（名称、皮肤ID、斗篷ID）
    - 响应：ProfileInfo
    - 错误：400（参数错误）、401（未授权）、403（无权操作）、404（档案不存在）、500（服务器错误）
  - DELETE /api/v1/profile/{uuid}
    - 路径参数：uuid
    - 响应：通用成功响应
    - 错误：401（未授权）、403（无权操作）、404（档案不存在）、500（服务器错误）
  - POST /api/v1/profile/{uuid}/activate
    - 路径参数：uuid
    - 响应：通用成功响应
    - 错误：401（未授权）、403（无权操作）、404（档案不存在）、500（服务器错误）

参数与校验要点
- CreateProfileRequest：名称长度1-16
- UpdateProfileRequest：名称长度1-16，皮肤/斗篷ID可选

章节来源
- [routes.go](file://internal/handler/routes.go#L63-L79)
- [profile_handler.go](file://internal/handler/profile_handler.go#L15-L93)
- [profile_handler.go](file://internal/handler/profile_handler.go#L95-L151)
- [profile_handler.go](file://internal/handler/profile_handler.go#L153-L195)
- [profile_handler.go](file://internal/handler/profile_handler.go#L197-L280)
- [profile_handler.go](file://internal/handler/profile_handler.go#L282-L339)
- [profile_handler.go](file://internal/handler/profile_handler.go#L341-L399)
- [common.go](file://internal/types/common.go#L81-L85)
- [common.go](file://internal/types/common.go#L201-L207)

### 验证码组（/api/v1/captcha）
- GET /api/v1/captcha/generate
  - 响应：主图、滑块图、验证码ID、Y坐标
  - 错误：500（生成失败）
- POST /api/v1/captcha/verify
  - 请求体：{captchaId, dx}
  - 响应：验证结果（成功/失败）
  - 错误：400（参数错误）、500（验证失败）

章节来源
- [routes.go](file://internal/handler/routes.go#L80-L85)
- [captcha_handler.go](file://internal/handler/captcha_handler.go#L11-L34)
- [captcha_handler.go](file://internal/handler/captcha_handler.go#L36-L77)

### Yggdrasil组（/api/v1/yggdrasil）
- 元数据
  - GET /api/v1/yggdrasil
    - 响应：实现信息、链接、特性开关、签名公钥、皮肤域名
- 认证服务
  - POST /api/v1/yggdrasil/authserver/authenticate
    - 请求体：AuthenticateRequest（agent、clientToken、identifier、password、requestUser）
    - 响应：AccessToken、ClientToken、SelectedProfile、AvailableProfiles、User（可选）
  - POST /api/v1/yggdrasil/authserver/validate
    - 请求体：ValidTokenRequest（accessToken、clientToken）
    - 响应：204（有效）或403（无效）
  - POST /api/v1/yggdrasil/authserver/refresh
    - 请求体：RefreshRequest（accessToken、clientToken、requestUser、selectedProfile）
    - 响应：新的AccessToken、ClientToken、SelectedProfile、User（可选）
  - POST /api/v1/yggdrasil/authserver/invalidate
    - 请求体：ValidTokenRequest（accessToken、clientToken）
    - 响应：204
  - POST /api/v1/yggdrasil/authserver/signout
    - 请求体：SignOutRequest（username、password）
    - 响应：204
- 会话服务
  - GET /api/v1/yggdrasil/sessionserver/session/minecraft/profile/{uuid}
    - 响应：序列化后的档案信息
  - POST /api/v1/yggdrasil/sessionserver/session/minecraft/join
    - 请求体：JoinServerRequest（serverId、accessToken、selectedProfile）
    - 响应：204 或错误
  - GET /api/v1/yggdrasil/sessionserver/session/minecraft/hasJoined
    - 查询：serverId、username、ip
    - 响应：200（Profile）或204（无内容）
- API服务
  - POST /api/v1/yggdrasil/api/profiles/minecraft
    - 请求体：字符串数组（玩家名）
    - 响应：Profile列表

参数与校验要点
- 认证/验证/刷新/登出：均需严格校验请求体字段与类型
- 会话验证：serverId与username必填
- 批量查询：名称数组非空

章节来源
- [routes.go](file://internal/handler/routes.go#L87-L111)
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L156-L246)
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L248-L267)
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L269-L361)
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L363-L378)
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L380-L425)
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L427-L447)
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L449-L496)
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L498-L552)
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L554-L587)
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L589-L616)
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L618-L666)

### 系统组（/api/v1/system）
- GET /api/v1/system/config
  - 响应：站点名称、描述、注册开关、每用户最大材质数、每用户最大档案数
  - 注意：当前实现为占位返回固定配置

章节来源
- [routes.go](file://internal/handler/routes.go#L112-L118)
- [routes.go](file://internal/handler/routes.go#L120-L140)

## 依赖分析
- 路由与中间件
  - 路由文件按组挂载鉴权中间件，确保受保护端点仅接受有效JWT
- 处理器与服务
  - 处理器通过服务层完成业务逻辑，服务层再与数据库/缓存交互
- 响应与类型
  - 统一响应结构与分页结构，类型定义集中约束参数范围与格式

```mermaid
graph LR
Routes["路由注册<br/>routes.go"] --> MW["鉴权中间件<br/>auth.go"]
MW --> Handlers["各处理器<br/>auth/user/texture/profile/captcha/yggdrasil"]
Handlers --> Services["服务层"]
Services --> DB["数据库/缓存"]
Handlers --> Models["响应模型<br/>response.go"]
Handlers --> Types["类型定义<br/>common.go"]
```

图表来源
- [routes.go](file://internal/handler/routes.go#L10-L118)
- [auth.go](file://internal/middleware/auth.go#L12-L56)
- [response.go](file://internal/model/response.go#L1-L86)
- [common.go](file://internal/types/common.go#L1-L215)

章节来源
- [routes.go](file://internal/handler/routes.go#L10-L118)
- [auth.go](file://internal/middleware/auth.go#L12-L56)
- [response.go](file://internal/model/response.go#L1-L86)
- [common.go](file://internal/types/common.go#L1-L215)

## 性能考虑
- 上传URL预签名
  - 材质与头像上传URL均采用预签名策略，缩短上传路径、降低后端压力
- 分页与限制
  - 材质与档案列表默认分页，避免一次性返回大量数据
  - 材质与档案数量限制（当前代码中硬编码，建议从配置读取）
- 缓存与日志
  - Redis用于验证码与公钥等缓存，减少数据库压力
  - 日志记录关键错误，便于追踪与优化
- 并发与超时
  - 建议为外部服务（如对象存储）设置合理超时与重试策略

## 故障排查指南
- 鉴权失败
  - 缺少Authorization头或格式不正确（401）
  - 无效token（401）
- 参数错误
  - JSON绑定失败或字段校验不通过（400）
- 资源不存在
  - 用户、档案、材质不存在（404）
- 权限不足
  - 非本人操作（403）
- 服务器错误
  - 数据库异常、外部服务不可用（500）

章节来源
- [auth.go](file://internal/middleware/auth.go#L12-L56)
- [response.go](file://internal/model/response.go#L27-L52)
- [auth_handler.go](file://internal/handler/auth_handler.go#L17-L84)
- [user_handler.go](file://internal/handler/user_handler.go#L70-L193)
- [texture_handler.go](file://internal/handler/texture_handler.go#L225-L291)
- [profile_handler.go](file://internal/handler/profile_handler.go#L197-L280)

## 结论
本API参考基于现有路由与处理器注释，梳理了CarrotSkin后端的核心REST接口与鉴权机制。建议在生产环境中：
- 将硬编码限制与默认值迁移至配置中心
- 引入速率限制与防刷策略
- 对敏感接口增加审计日志
- 完善单元测试与集成测试覆盖

## 附录

### 统一响应结构
- 成功响应：包含code、message、data
- 分页响应：包含code、message、data、total、page、per_page
- 错误响应：包含code、message、error（开发环境）

章节来源
- [response.go](file://internal/model/response.go#L1-L86)

### 常见错误码
- 200：成功
- 400：请求参数错误
- 401：未授权
- 403：禁止访问
- 404：资源不存在
- 500：服务器内部错误

章节来源
- [response.go](file://internal/model/response.go#L27-L52)

### Swagger与健康检查
- 文档地址：/swagger/*any
- 健康检查：/health

章节来源
- [swagger.go](file://internal/handler/swagger.go#L41-L63)