认证API

本文档引用的文件

auth.controller.ts
auth.service.ts
auth.ts
rate-limiter.ts
app.ts
errorHandler.ts
index.ts
index.ts
index.ts

简介

本文件为音频TTS平台的认证模块API文档，涵盖以下三个核心接口：

发送验证码接口：POST /api/auth/send-code
手机号登录接口：POST /api/auth/login
获取用户信息接口：GET /api/auth/user-info

文档详细说明了每个接口的请求参数、响应格式、HTTP状态码和错误处理机制，并提供了完整的请求示例和响应示例，包括成功和失败场景。同时说明了JWT令牌的使用方式和认证头部的设置方法，包含安全考虑、频率限制和最佳实践建议。

项目结构

认证模块采用分层架构设计，主要包含以下层次：

graph TB
subgraph "应用层"
Router[路由层]
Controller[控制器层]
end
subgraph "业务逻辑层"
Service[服务层]
end
subgraph "基础设施层"
Middleware[中间件层]
Database[(数据库)]
Redis[(Redis缓存)]
end
subgraph "外部服务"
SMS[短信服务]
Storage[存储服务]
end
Router --> Controller
Controller --> Service
Service --> Database
Service --> Redis
Service --> SMS
Controller --> Middleware
Middleware --> Service

图表来源

auth.controller.ts:1-94
auth.service.ts:1-115
auth.ts:1-81

章节来源

auth.controller.ts:1-94
auth.service.ts:1-115
auth.ts:1-81

核心组件

路由与控制器

认证模块通过Koa Router提供RESTful API接口，采用模块化设计，每个接口都有独立的路由处理函数。

服务层

服务层封装了核心业务逻辑，包括：

验证码生成与验证
JWT令牌生成与验证
用户信息管理
数据库操作

中间件层

中间件层提供认证、授权、频率限制等横切关注点，确保系统的安全性和稳定性。

章节来源

auth.controller.ts:10-64
auth.service.ts:10-97
auth.ts:7-49

架构概览

认证系统的整体架构如下：

sequenceDiagram
participant Client as 客户端
participant Router as 路由器
participant Controller as 控制器
participant Service as 服务层
participant DB as 数据库
participant Redis as Redis缓存
Client->>Router : HTTP请求
Router->>Controller : 调用对应处理函数
Controller->>Service : 执行业务逻辑
Service->>DB : 查询/更新用户信息
Service->>Redis : 缓存验证码
Service-->>Controller : 返回处理结果
Controller-->>Client : HTTP响应
Note over Client,DB : 认证流程中涉及JWT令牌验证

图表来源

app.ts:100
auth.controller.ts:1-94
auth.service.ts:1-115

详细组件分析

发送验证码接口

接口定义

URL: POST /api/auth/send-code
功能: 向指定手机号发送验证码
认证: 无需认证

请求参数

参数名	类型	必填	描述	示例
phone	string	是	手机号码	"13800001111"

响应格式

成功响应:

{
  "code": 0,
  "message": "验证码发送成功",
  "data": {
    "phone": "13800001111",
    "code": "1234"
  }
}

失败响应:

{
  "code": 400,
  "message": "请输入正确的手机号",
  "data": null
}

HTTP状态码

200: 请求成功
400: 参数验证失败
500: 服务器内部错误

业务逻辑

flowchart TD
Start([开始]) --> ValidatePhone[验证手机号格式]
ValidatePhone --> PhoneValid{手机号有效?}
PhoneValid --> |否| ReturnError[返回错误]
PhoneValid --> |是| GenerateCode[生成验证码]
GenerateCode --> StoreCode[存储到Redis/内存]
StoreCode --> ReturnSuccess[返回成功响应]
ReturnError --> End([结束])
ReturnSuccess --> End

图表来源

auth.controller.ts:11-30
auth.service.ts:11-19

章节来源

auth.controller.ts:11-30
auth.service.ts:11-19

手机号登录接口

接口定义

URL: POST /api/auth/login
功能: 使用手机号进行登录或注册
认证: 无需认证

请求参数

参数名	类型	必填	描述	示例
phone	string	是	手机号码	"13800001111"
code	string	否	验证码	"123456"

响应格式

成功响应:

{
  "code": 0,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": "123",
      "phone": "13800001111",
      "nickname": "用户1111",
      "avatar": "https://api.dicebear.com/...",
      "memberLevel": 0,
      "isNewUser": true
    }
  }
}

失败响应:

{
  "code": 400,
  "message": "验证码错误或已过期",
  "data": null
}

HTTP状态码

200: 登录成功
400: 验证失败或参数错误
500: 服务器内部错误

登录流程

sequenceDiagram
participant Client as 客户端
participant Controller as 控制器
participant Service as 服务层
participant DB as 数据库
Client->>Controller : POST /api/auth/login
Controller->>Controller : 验证手机号格式
Controller->>Service : loginWithPhone(phone, code)
Service->>Service : 验证验证码(可选)
Service->>DB : 查找用户或创建新用户
DB-->>Service : 用户信息
Service->>Service : 生成JWT令牌
Service-->>Controller : 返回登录结果
Controller-->>Client : 返回登录响应

图表来源

auth.controller.ts:33-52
auth.service.ts:44-97

章节来源

auth.controller.ts:33-52
auth.service.ts:44-97

获取用户信息接口

接口定义

URL: GET /api/auth/user-info
功能: 获取当前登录用户的详细信息
认证: 需要JWT认证

请求参数

无查询参数

响应格式

成功响应:

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "123",
    "phone": "13800001111",
    "nickname": "用户1111",
    "avatar": "https://api.dicebear.com/...",
    "memberLevel": 0,
    "memberExpireAt": "",
    "dailyUsage": 0
  }
}

失败响应:

{
  "code": 401,
  "message": "Token 已过期",
  "data": null
}

HTTP状态码

200: 获取成功
401: 未授权或Token无效
404: 用户不存在
500: 服务器内部错误

认证流程

flowchart TD
Start([开始]) --> CheckAuthHeader[检查Authorization头]
CheckAuthHeader --> HasAuth{存在认证头?}
HasAuth --> |否| ReturnUnauthorized[返回401]
HasAuth --> |是| ParseToken[解析Bearer Token]
ParseToken --> VerifyToken[验证JWT令牌]
VerifyToken --> TokenValid{令牌有效?}
TokenValid --> |否| ReturnInvalidToken[返回401]
TokenValid --> |是| GetUser[获取用户信息]
GetUser --> ReturnUserInfo[返回用户信息]
ReturnUnauthorized --> End([结束])
ReturnInvalidToken --> End
ReturnUserInfo --> End

图表来源

auth.ts:20-49
auth.controller.ts:55-64

章节来源

auth.controller.ts:55-64
auth.ts:20-49

依赖关系分析

组件依赖图

graph TB
subgraph "外部依赖"
JWT[jsonwebtoken]
Prisma[Prisma Client]
Redis[Redis]
end
subgraph "内部模块"
AuthController[auth.controller.ts]
AuthService[auth.service.ts]
AuthMiddleware[auth.ts]
ErrorHandler[errorHandler.ts]
RateLimiter[rate-limiter.ts]
Config[config.ts]
Types[index.ts]
Models[index.ts]
end
AuthController --> AuthService
AuthController --> AuthMiddleware
AuthController --> ErrorHandler
AuthService --> Prisma
AuthService --> JWT
AuthService --> Redis
AuthMiddleware --> JWT
AuthMiddleware --> ErrorHandler
RateLimiter --> Redis
Config --> AuthMiddleware
Types --> AuthController
Models --> AuthService

图表来源

auth.controller.ts:1-7
auth.service.ts:1-5
auth.ts:1-5
rate-limiter.ts:1-2

数据流分析

erDiagram
USER {
int id PK
string phone
string nickname
string avatar
int memberLevel
int dailyUsage
string lastUsageDate
datetime createdAt
datetime updatedAt
}
SMS_CODE {
string phone PK
string code
datetime expireAt
}
JWT_TOKEN {
string userId
string phone
datetime iat
datetime exp
}
USER ||--o{ JWT_TOKEN : "拥有"
USER ||--o{ SMS_CODE : "关联"

图表来源

index.ts:4-16
auth.service.ts:7-32

章节来源

auth.controller.ts:1-94
auth.service.ts:1-115
auth.ts:1-81

性能考虑

频率限制策略

系统实现了多层级的频率限制机制：

限制类型	配置	说明
全局限流	100次/分钟	对整个API进行总体限制
登录接口	5次/分钟	防止暴力破解
验证码发送	1次/分钟	防止短信轰炸
TTS生成	20次/分钟	根据用户等级限制
文件上传	10次/分钟	限制上传频率

缓存策略

验证码缓存: 使用内存Map存储，生产环境建议使用Redis
用户会话: JWT令牌存储在客户端，减少服务器状态
配置缓存: 应用启动时加载并缓存配置信息

性能优化建议

Redis迁移: 生产环境建议将验证码存储从内存迁移到Redis
连接池: 使用数据库连接池提高并发性能
缓存预热: 对热点用户信息进行缓存预热
异步处理: 将耗时操作（如短信发送）改为异步处理

故障排除指南

常见错误及解决方案

认证相关错误

业务逻辑错误

错误类型	HTTP状态码	错误信息	解决方案
缺少认证头	401	缺少 Authorization 头	在请求头添加Authorization: Bearer
Token格式错误	401	Authorization 格式错误	确保使用Bearer前缀和有效的JWT令牌
Token过期	401	Token 已过期	重新登录获取新令牌
Token无效	401	Token 无效	检查令牌签名和有效期

错误类型	HTTP状态码	错误信息	解决方案
手机号格式错误	400	请输入正确的手机号	验证手机号格式为11位数字
验证码错误	400	验证码错误或已过期	检查验证码是否正确且未过期
用户不存在	404	用户不存在	确认用户已注册或重新登录

频率限制错误

错误类型	HTTP状态码	错误信息	解决方案
请求过于频繁	429	请求过于频繁，请稍后再试	等待Retry-After指定的时间后重试

调试技巧

开发环境认证: 设置环境变量AUTH_ENABLED=false可跳过认证
详细错误日志: 开发环境下会返回完整的错误堆栈信息
请求追踪: 使用Sentry进行错误监控和追踪

章节来源

auth.ts:8-18
errorHandler.ts:3-24
rate-limiter.ts:60-71

结论

认证模块提供了完整的移动端用户认证解决方案，具有以下特点：

安全特性

JWT令牌认证机制
多层频率限制
输入参数验证
XSS和SQL注入防护

可扩展性

模块化设计便于维护
中间件架构支持功能扩展
配置驱动的认证策略

最佳实践建议

生产环境部署: 启用认证中间件，使用Redis存储验证码
安全配置: 使用强密码学密钥，定期轮换JWT密钥
监控告警: 集成Sentry进行错误监控，设置合理的告警阈值
性能优化: 实施缓存策略，使用连接池和异步处理

该认证模块为音频TTS平台提供了可靠的基础设施，支持后续功能的扩展和演进。

认证API.md 14 KB História Raw

认证API

目录

简介

项目结构

核心组件

路由与控制器

服务层

中间件层

架构概览

详细组件分析

发送验证码接口

接口定义

请求参数

响应格式

HTTP状态码

业务逻辑

手机号登录接口

接口定义

请求参数

响应格式

HTTP状态码

登录流程

获取用户信息接口

接口定义

请求参数

响应格式

HTTP状态码

认证流程

依赖关系分析

组件依赖图

数据流分析

性能考虑

频率限制策略

缓存策略

性能优化建议

故障排除指南

常见错误及解决方案

认证相关错误

业务逻辑错误

频率限制错误

调试技巧

结论

安全特性

可扩展性

最佳实践建议

认证API.md 14 KB

História Raw