API 使用文档
目录
快速开始
基础信息
- API基础URL:
https://your-domain.com/api - 请求格式: JSON
- 响应格式: JSON
- 字符编码: UTF-8
获取API密钥
- 登录管理后台
- 进入"站点管理"
- 创建或编辑站点
- 复制站点的API密钥
网站配置说明
每个网站都有独立的配置参数，这些参数会影响API的行为：
限制配置
- IP注册限制 (
ip_limit): 单个IP在24小时内最多可注册的用户数量，0表示无限制 - IP请求频率限制 (
rate_limit): 单个IP每分钟最多可发送的API请求数量，0表示无限制
用户配置
- 用户名最小长度 (
username_min_length): 用户名的最小长度限制，建议3-50位 - 用户名最大长度 (
username_max_length): 用户名的最大长度限制，建议3-50位
Token配置
- Token长度 (
token_length): 用户Token的长度，0表示使用系统默认设置 - Token过期时间 (
token_expire_time): Token的有效期（秒），0表示永不过期 - 登录时Token重置 (
token_reset_on_login): 登录时是否重置Token，1=重置，0=不重置
安全配置
- 账号最大失败尝试次数 (
account_max_attempts): 单个账号连续失败登录的最大次数 - 账号锁定时间 (
account_lock_time): 账号被锁定后的持续时间（秒） - IP最大失败尝试次数 (
ip_max_attempts): 单个IP地址连续失败登录的最大次数 - IP锁定时间 (
ip_lock_time): IP被锁定后的持续时间（秒）
其他配置
- 在线状态判定阈值 (
online_threshold_seconds): 用于判定用户是否在线的心跳时间阈值（秒）
认证方式
API密钥认证
所有API请求都需要在HTTP Header中携带站点API密钥：
X-API-Key: your_website_api_keyToken认证
需要用户身份的接口需要同时携带用户Token：
X-API-Key: your_website_api_key
X-User-Token: user_token_here注意: 系统使用 X-User-Token 头进行用户身份验证，不支持 Authorization: Bearer 格式。
Token过期时间说明
- 格式: 时间戳（整数）
- 永不过期: 返回
-1 - 已过期: 返回具体的时间戳值
- 示例:
1760781768表示2025年11月17日过期
注意: 当 expires_at 为 -1 时，表示该Token永不过期，客户端无需检查过期时间。
用户认证接口
1. 用户注册
接口地址: POST /api/auth/register
注意事项:
- account 必须唯一，只能包含字母、数字、下划线
- password 可选，如果不设置密码，用户可以无密码登录
- email 可选，但如果需要密码找回功能，建议填写
请求Header:
X-API-Key: your_api_key请求参数:
{
"account": "user123",
"password": "password123",
"email": "user@example.com"
}参数说明:
- account // 必填，用户账号（只能包含字母、数字、下划线）
- password // 可选，密码（至少8位，包含字母和数字）
- email // 可选，邮箱地址
响应示例:
{
"code": 200,
"msg": "Registration successful",
"timestamp": 1729162042,
"data": {
"user_id": 1,
"account": "user123",
"email": "user@example.com",
"token": "abc123def456...",
"expires_at": 1760781768,
"has_password": true
}
}返回参数说明:
- code // 响应状态码，200表示成功
- msg // 响应消息
- timestamp // 响应时间戳
- data.user_id // 用户ID
- data.account // 用户账号
- data.email // 用户邮箱
- data.token // 用户令牌
- data.expires_at // 令牌过期时间（-1表示永不过期）
- data.has_password // 是否设置了密码
- data.user_info // 用户详细信息（当include_user_info=true时返回）
- data.user_data // 用户字段数据（当include_user_data=true时返回）
2. 用户登录
接口地址: POST /api/auth/login
注意事项:
- 微信用户无法通过此接口登录
- 微信用户必须使用
/api/wechat/auth接口登录
请求Header:
X-API-Key: your_api_key请求参数:
{
"account": "user123",
"password": "password123",
"include_user_info": true,
"include_user_data": true
}
参数说明:
- account // 必填，用户账号（只能包含字母、数字、下划线）
- password // 可选，密码（如果用户设置了密码则必填）
- include_user_info // 可选，是否返回用户基本信息（布尔值）
- include_user_data // 可选，是否返回用户字段数据（布尔值）
响应示例:
{
"code": 200,
"msg": "Login successful",
"timestamp": 1729162042,
"data": {
"user_id": 1,
"account": "user123",
"email": "user@example.com",
"token": "xyz789abc123...",
"expires_at": 1760781768,
"has_password": true,
"user_info": {
"id": 1,
"account": "user123",
"email": "user@example.com",
"email_verified": 1,
"status": 1,
"last_login_at": "2025-10-17 10:47:22",
"last_heartbeat_at": "2025-10-17 10:47:22",
"created_at": "2025-10-17 09:30:00"
},
"user_data": {
"nickname": "用户昵称",
"avatar": "https://example.com/avatar.jpg",
"phone": "13800138000",
"age": 25
}
}
}返回参数说明:
- code // 响应状态码，200表示成功
- msg // 响应消息
- timestamp // 响应时间戳
- data.user_id // 用户ID
- data.account // 用户账号
- data.email // 用户邮箱
- data.token // 用户令牌
- data.expires_at // 令牌过期时间（-1表示永不过期）
- data.has_password // 是否设置了密码
- data.user_info // 用户详细信息（当include_user_info=true时返回）
- data.user_data // 用户字段数据（当include_user_data=true时返回）
3. 心跳检测
接口地址: GET /api/auth/heartbeat
请求Header:
X-API-Key: your_api_key
X-User-Token: user_token响应示例:
{
"code": 200,
"msg": "Heartbeat successful",
"timestamp": 1729162042,
"data": {
"status": "online",
"last_heartbeat": "2025-10-17 10:47:22",
"expires_at": 1760781768,
"is_online": true
}
}使用场景:
- 更新用户最后活跃时间
- 检测Token是否有效
- 保持用户在线状态
5. 忘记密码
接口地址: POST /api/auth/forgot-password
注意事项:
- 不需要用户登录状态
- 账号和邮箱必须匹配
- 重置令牌有效期为24小时
- 微信用户无法使用此功能（微信用户无密码）
请求Header:
X-API-Key: your_api_key请求参数:
{
"account": "user123",
"email": "user@example.com"
}参数说明:
- account // 必填，用户账号
- email // 必填，注册时使用的邮箱
响应示例:
{
"code": 200,
"msg": "Password reset link generated",
"timestamp": 1729162042,
"data": {
"message": "重置链接已生成",
"reset_token": "reset_token_here",
"expires_at": 1760781768
}
}返回参数说明:
- code // 响应状态码，200表示成功
- msg // 响应消息
- timestamp // 响应时间戳
- data.message // 提示消息
- data.reset_token // 密码重置令牌
- data.expires_at // 令牌过期时间
注意事项:
- 需要在后台配置邮件服务
- 重置令牌有效期为1小时
6. 重置密码
接口地址: POST /api/auth/reset-password
注意事项:
- 不需要用户登录状态
- 重置令牌必须有效且未过期
- 新密码必须符合密码强度要求
- 重置成功后令牌失效
请求Header:
X-API-Key: your_api_key请求参数:
{
"reset_token": "reset_token_here",
"new_password": "newpassword123"
}参数说明:
- reset_token // 必填，密码重置令牌
- new_password // 必填，新密码（至少8位，包含字母和数字）
响应示例:
{
"code": 200,
"msg": "Password reset successful",
"timestamp": 1729162042,
"data": {
"message": "密码重置成功",
"new_token": "new_token_here",
"expires_at": "2025-11-17 10:47:22"
}
}返回参数说明:
- code // 响应状态码，200表示成功
- msg // 响应消息
- timestamp // 响应时间戳
- data.message // 提示消息
- data.new_token // 新的用户令牌
- data.expires_at // 令牌过期时间
4. 修改密码
接口地址: POST /api/auth/change-password
注意事项:
- 需要用户登录状态
- 新密码必须符合密码强度要求（至少8位，包含字母和数字）
- 微信用户无法修改密码（微信用户无密码）
请求Header:
X-API-Key: your_api_key
X-User-Token: user_token请求参数:
{
"old_password": "oldpassword123",
"new_password": "newpassword456"
}参数说明:
- old_password // 必填，当前密码
- new_password // 必填，新密码（至少8位，包含字母和数字）
响应示例:
{
"code": 200,
"msg": "Password changed successful",
"timestamp": 1729162042,
"data": {
"message": "密码修改成功"
}
}返回参数说明:
- code // 响应状态码，200表示成功
- msg // 响应消息
- timestamp // 响应时间戳
- data.message // 提示消息
3. 微信小程序登录
接口地址: POST /api/wechat/auth
注意事项:
- 需要在后台配置微信小程序AppID和AppSecret
- 返回的
is_new_user字段表示是否为新用户 token_expires_at-1表示永不过期- 微信用户的
account字段返回wechat_user，不暴露真实的openid
请求Header:
X-API-Key: your_api_key请求参数:
{
"code": "081xYz000...",
"encryptedData": "...",
"iv": "..."
}参数说明:
- code // 必填，微信小程序登录凭证
- encryptedData // 可选，加密的用户数据
- iv // 可选，加密算法的初始向量
响应示例:
{
"code": 200,
"msg": "WeChat authentication successful",
"timestamp": 1729162042,
"data": {
"user_id": 1,
"token": "abc123def456...",
"token_expires_at": 1760781768,
"is_new_user": false
}
}返回参数说明:
- code // 响应状态码，200表示成功
- msg // 响应消息
- timestamp // 响应时间戳
- data.user_id // 用户ID
- data.token // 用户令牌
- data.token_expires_at // 令牌过期时间（-1表示永不过期）
- data.is_new_user // 是否为新用户（布尔值）
用户信息接口
2. 获取用户详细信息
接口地址: GET /api/user/info
注意事项:
- 需要用户登录状态
- 微信用户的
account字段返回wechat_user - 返回用户完整信息和字段数据
请求Header:
X-API-Key: your_api_key
X-User-Token: user_token参数说明:
- 无需请求参数
响应示例:
{
"code": 200,
"msg": "Success",
"timestamp": 1729162042,
"data": {
"user": {
"id": 1,
"account": "user123",
"email": "user@example.com",
"email_verified": 1,
"status": 1,
"last_login_at": "2025-10-17 10:47:22",
"last_heartbeat_at": "2025-10-17 10:47:22",
"created_at": "2025-10-17 09:30:00"
}
}
}返回参数说明:
- code // 响应状态码，200表示成功
- msg // 响应消息
- timestamp // 响应时间戳
- data.user // 用户基本信息对象
- data.user.id // 用户ID
- data.user.account // 用户账号（微信用户返回wechat_user）
- data.user.email // 用户邮箱
- data.user.email_verified // 邮箱是否验证
- data.user.status // 用户状态
- data.user.last_login_at // 最后登录时间
- data.user.last_heartbeat_at // 最后心跳时间
- data.user.created_at // 创建时间
用户数据接口
1. 获取用户数据
接口地址: GET /api/user/data
注意事项:
- 需要用户登录状态
- 微信用户的
account字段返回wechat_user - 返回所有用户字段数据
- 数据可能经过加密，需要客户端解密
请求Header:
X-API-Key: your_api_key
X-User-Token: user_token请求参数:
- 无需请求参数
响应示例:
{
"code": 200,
"msg": "Success",
"timestamp": 1729162042,
"data": {
"user_id": 1,
"account": "user123",
"email": "user@example.com",
"data": {
"nickname": "用户昵称",
"avatar": "https://example.com/avatar.jpg",
"phone": "13800138000",
"age": 25,
"vip_level": 3,
"game_score": 9999
}
}
}返回参数说明:
- code // 响应状态码，200表示成功
- msg // 响应消息
- timestamp // 响应时间戳
- data.user_id // 用户ID
- data.account // 用户账号（微信用户返回wechat_user）
- data.email // 用户邮箱
- data.data // 用户字段数据对象
注意事项:
- 返回的数据包含字段默认值（仅返回有默认值的字段）
- 如果字段不存在且没有默认值，不会返回该字段
2. 更新用户数据
接口地址: PUT /api/user/data
注意事项:
- 需要用户登录状态
- 支持批量更新多个字段
- 只更新提供的字段，未提供的字段保持不变
- 字段值需要符合字段定义的类型和长度限制
请求Header:
X-API-Key: your_api_key
X-User-Token: user_token
Content-Type: application/json请求参数:
{
"nickname": "新昵称",
"avatar": "https://new-avatar.jpg",
"phone": "13900139000",
"age": 26,
"custom_field1": "value1",
"custom_field2": "value2"
}参数说明:
- 字段名 // 可选，要更新的字段名和对应的值
- 支持所有已定义的字段类型（字符串、数字、布尔值等）
响应示例:
{
"code": 200,
"msg": "Data updated successfully",
"timestamp": 1729162042,
"data": null
}返回参数说明:
- code // 响应状态码，200表示成功
- msg // 响应消息
- timestamp // 响应时间戳
- data // 通常为null
注意事项:
- 可以一次更新多个字段
- 只能更新在后台配置的字段
- 字段类型会自动验证
3. 删除用户数据字段
接口地址: DELETE /api/user/data
注意事项:
- 需要用户登录状态
- 只能删除用户自定义字段，不能删除系统字段
- 删除操作不可恢复
请求Header:
X-API-Key: your_api_key
X-User-Token: user_token请求参数:
{
"field_name": "custom_field1"
}参数说明:
- field_name // 必填，要删除的字段名
响应示例:
{
"code": 200,
"msg": "Data deleted successfully",
"timestamp": 1729162042,
"data": null
}返回参数说明:
- code // 响应状态码，200表示成功
- msg // 响应消息
- timestamp // 响应时间戳
- data // 通常为null
其他接口
1. 获取字段配置
接口地址: GET /api/fields
请求Header:
X-API-Key: your_api_key响应示例:
{
"code": 200,
"msg": "Success",
"timestamp": 1729162042,
"data": [
{
"field_name": "nickname",
"field_type": "string",
"field_length": 255,
"is_required": 0,
"default_value": "",
"description": "用户昵称"
},
{
"field_name": "age",
"field_type": "number",
"field_length": 11,
"is_required": 0,
"default_value": "0",
"description": "用户年龄"
}
]
}2. 获取网站信息
接口地址: GET /api/website
请求Header:
X-API-Key: your_api_key响应示例:
{
"code": 200,
"msg": "Success",
"timestamp": 1729162042,
"data": {
"website": {
"id": 1,
"name": "我的网站",
"domain": "https://example.com",
"description": "网站描述",
"status": 1,
"created_at": "2025-10-17 09:00:00"
}
}
}3. 连通性测试
接口地址: GET /api/ping
请求Header: 无需认证
响应示例:
{
"code": 200,
"msg": "pong",
"timestamp": 1729162042,
"data": {
"time": 1729162042
}
}错误码说明
HTTP状态码
200- 请求成功400- 请求参数错误401- 未授权（Token无效或过期）403- 禁止访问（API密钥无效或站点被禁用）404- 资源不存在429- 请求过于频繁500- 服务器内部错误
响应格式
所有响应都遵循统一格式：
{
"code": 200, // 状态码
"msg": "Success", // 消息描述
"timestamp": 1729162042, // 服务器时间戳
"data": {} // 响应数据
}常见错误示例
API密钥无效:
{
"code": 401,
"msg": "Invalid API Key or website not found",
"timestamp": 1729162042,
"data": null
}Token无效:
{
"code": 401,
"msg": "Invalid token or user not found",
"timestamp": 1729162042,
"data": null
}账号已存在:
{
"code": 400,
"msg": "Account already exists",
"timestamp": 1729162042,
"data": null
}密码错误:
{
"code": 401,
"msg": "Invalid password",
"timestamp": 1729162042,
"data": null
}请求频率限制:
{
"code": 429,
"msg": "IP rate limit: too many requests, please retry after 45 seconds",
"timestamp": 1729162042,
"data": null
}网站被禁用:
{
"code": 403,
"msg": "Website is disabled",
"timestamp": 1729162042,
"data": null
}IP注册限制:
{
"code": 429,
"msg": "IP register limit reached: too many registrations in 24h",
"timestamp": 1729162042,
"data": null
}账号被锁定:
{
"code": 429,
"msg": "Account is locked, please try again later",
"timestamp": 1729162042,
"data": null
}IP地址被锁定:
{
"code": 429,
"msg": "IP address is locked, please try again later",
"timestamp": 1729162042,
"data": null
}微信用户登录限制:
{
"code": 403,
"msg": "Wechat users must use Wechat login interface",
"timestamp": 1729162042,
"data": null
}微信小程序功能未启用:
{
"code": 403,
"msg": "WeChat mini-program registration is disabled",
"timestamp": 1729162042,
"data": null
}API交互流程
完整交互流程图
sequenceDiagram
participant Client as 客户端应用
participant API as API服务器
participant DB as 数据库
Note over Client,DB: 1. 初始化阶段
Client->>API: GET /api/ping (测试连通性)
API-->>Client: 返回服务器状态
Client->>API: GET /api/website (获取站点信息)
API->>DB: 查询站点配置
DB-->>API: 返回站点数据
API-->>Client: 返回站点信息
Client->>API: GET /api/fields (获取字段配置)
API->>DB: 查询字段定义
DB-->>API: 返回字段列表
API-->>Client: 返回字段配置
Note over Client,DB: 2. 用户认证阶段
alt 新用户注册
Client->>API: POST /api/auth/register<br/>{account, password, email}
API->>DB: 检查账号是否存在
DB-->>API: 账号不存在
API->>DB: 创建用户记录
API->>DB: 生成Token
DB-->>API: 保存成功
API-->>Client: 返回 {user_id, token, expires_at}
else 已有用户登录
Client->>API: POST /api/auth/login<br/>{account, password}
API->>DB: 验证账号密码
DB-->>API: 验证通过
API->>DB: 生成新Token
API->>DB: 更新最后登录时间
DB-->>API: 更新成功
API-->>Client: 返回 {user_id, token, user_info, user_data}
else 微信小程序登录
Client->>API: POST /api/wechat/auth<br/>{code}
API->>WeChat: 调用微信API获取openid
WeChat-->>API: 返回openid
API->>DB: 查询或创建用户
API->>DB: 生成Token
DB-->>API: 保存成功
API-->>Client: 返回 {user_id, token, openid}
end
Note over Client,DB: 3. 业务操作阶段
Client->>API: GET /api/auth/heartbeat<br/>Header: Authorization
API->>DB: 验证Token
DB-->>API: Token有效
API->>DB: 更新心跳时间
API-->>Client: 返回心跳成功
Client->>API: GET /api/user/data<br/>Header: Authorization
API->>DB: 验证Token
API->>DB: 查询用户数据
DB-->>API: 返回用户数据
API-->>Client: 返回所有字段数据
Client->>API: PUT /api/user/data<br/>{nickname, avatar, ...}
API->>DB: 验证Token
API->>DB: 更新用户数据
DB-->>API: 更新成功
API-->>Client: 返回更新结果
Note over Client,DB: 4. 密码管理（可选）
alt 修改密码
Client->>API: POST /api/auth/change-password<br/>{old_password, new_password}
API->>DB: 验证旧密码
API->>DB: 更新新密码
API-->>Client: 修改成功
else 忘记密码
Client->>API: POST /api/auth/forgot-password<br/>{account, email}
API->>DB: 验证账号和邮箱
API->>Email: 发送重置邮件
API-->>Client: 邮件已发送
Client->>API: POST /api/auth/reset-password<br/>{reset_token, new_password}
API->>DB: 验证重置令牌
API->>DB: 更新密码
API-->>Client: 重置成功
end接口调用关系表
| 阶段 | 接口 | 方法 | 需要API Key | 需要Token | 说明 |
|------|------|------|-------------|-----------|------|
| 初始化 | /api/ping | GET | ❌ | ❌ | 测试API连通性 |
| | /api/website | GET | ✅ | ❌ | 获取站点配置信息 |
| | /api/fields | GET | ✅ | ❌ | 获取字段定义 |
| 认证 | /api/auth/register | POST | ✅ | ❌ | 新用户注册 |
| | /api/auth/login | POST | ✅ | ❌ | 用户登录 |
| | /api/wechat/auth | POST | ✅ | ❌ | 微信小程序登录 |
| 用户信息 | /api/me | GET | ✅ | ✅ | 获取当前用户基本信息 |
| | /api/user/info | GET | ✅ | ✅ | 获取用户完整信息 |
| 用户数据 | /api/user/data | GET | ✅ | ✅ | 获取用户字段数据 |
| | /api/user/data | PUT | ✅ | ✅ | 更新用户字段数据 |
| | /api/user/data | DELETE | ✅ | ✅ | 删除用户字段数据 |
| 密码管理 | /api/auth/change-password | POST | ✅ | ✅ | 修改密码（需登录）|
| | /api/auth/forgot-password | POST | ✅ | ❌ | 忘记密码（发送邮件）|
| | /api/auth/reset-password | POST | ✅ | ❌ | 重置密码（使用令牌）|
| 保活 | /api/auth/heartbeat | GET | ✅ | ✅ | 心跳检测，保持在线 |
典型使用场景
场景1：新用户首次使用
1. 测试连接 → GET /api/ping
2. 获取站点信息 → GET /api/website
3. 获取字段配置 → GET /api/fields
4. 用户注册 → POST /api/auth/register
5. 保存Token → 本地存储
6. 获取用户数据 → GET /api/user/data (使用Token)
7. 更新用户资料 → PUT /api/user/data (使用Token)场景2：老用户登录
1. 用户登录 → POST /api/auth/login (include_user_data=true)
2. 保存Token → 本地存储
3. 获取完整信息 → 登录接口已返回
4. 定期心跳 → GET /api/auth/heartbeat (每5分钟)
5. 更新数据 → PUT /api/user/data (按需)场景3：微信小程序
1. 微信登录 → wx.login() 获取code
2. 后台认证 → POST /api/wechat/auth {code}
3. 保存Token → wx.setStorageSync('token', token)
4. 获取用户数据 → GET /api/user/data
5. 更新用户资料 → PUT /api/user/data
6. 定期心跳 → GET /api/auth/heartbeat场景4：忘记密码
1. 请求重置 → POST /api/auth/forgot-password {account, email}
2. 接收邮件 → 用户查收邮件
3. 获取令牌 → 从邮件中获取reset_token
4. 重置密码 → POST /api/auth/reset-password {reset_token, new_password}
5. 重新登录 → POST /api/auth/login数据流转示意
┌─────────────────────────────────────────────────────────────────┐
│ 客户端应用层 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 登录界面 │ │ 主界面 │ │ 设置界面 │ │ 数据界面 │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
└───────┼─────────────┼─────────────┼─────────────┼───────────────┘
│ │ │ │
│ 1.注册/登录 │ 2.心跳保活 │ 3.修改密码 │ 4.数据操作
▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ API网关层 │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 请求验证: API Key → 站点验证 → Token验证 → 权限检查 │ │
│ └──────────────────────────────────────────────────────────┘ │
└───────┬─────────────┬─────────────┬─────────────┬───────────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ 业务逻辑层 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 用户认证 │ │ 会话管理 │ │ 密码管理 │ │ 数据管理 │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
└───────┼─────────────┼─────────────┼─────────────┼───────────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ 数据持久层 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ websites │ │ users │ │ tokens │ │user_data │ │
│ │ 表 │ │ 表 │ │ 表 │ │ 表 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────┘认证流程详解
客户端 服务器
│ │
│ 1. POST /api/auth/register │
│ Headers: X-API-Key │
│ Body: {account, password} │
├──────────────────────────────────────>│
│ │ 2. 验证API Key
│ │ 3. 检查账号是否存在
│ │ 4. 创建用户记录
│ │ 5. 生成Token (有效期30天)
│ │ 6. 保存Token到数据库
│ │
│ 7. 返回 {user_id, token, expires_at}│
│<──────────────────────────────────────┤
│ │
│ 8. 保存Token到本地 │
│ │
│ 9. GET /api/user/data │
│ Headers: │
│ X-API-Key: xxx │
│ Authorization: Bearer {token} │
├──────────────────────────────────────>│
│ │ 10. 验证API Key
│ │ 11. 验证Token
│ │ 12. 查询用户数据
│ │
│ 13. 返回用户数据 │
│<──────────────────────────────────────┤
│ │
│ 14. PUT /api/user/data │
│ Body: {nickname: "新昵称"} │
├──────────────────────────────────────>│
│ │ 15. 验证Token
│ │ 16. 验证字段配置
│ │ 17. 更新数据
│ │
│ 18. 返回更新结果 │
│<──────────────────────────────────────┤
│ │最佳实践
1. 错误处理
// JavaScript/TypeScript 示例
async function apiRequest(url, options = {}) {
try {
const response = await fetch(url, {
...options,
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'your_api_key',
...options.headers
}
});
const result = await response.json();
if (result.code === 200) {
return result.data;
} else {
throw new Error(result.msg);
}
} catch (error) {
console.error('API请求失败:', error);
throw error;
}
}2. Token管理
// 保存Token
function saveToken(token, expiresAt) {
localStorage.setItem('user_token', token);
localStorage.setItem('token_expires_at', expiresAt);
}
// 检查Token是否过期
function isTokenExpired() {
const expiresAt = localStorage.getItem('token_expires_at');
if (!expiresAt || expiresAt === '-1') return false; // -1表示永不过期
const expireTime = parseInt(expiresAt) * 1000; // 转换为毫秒
return Date.now() > expireTime;
}
// 获取Token
function getToken() {
if (isTokenExpired()) {
// 跳转到登录页
return null;
}
return localStorage.getItem('user_token');
}3. 心跳保活
// 定期发送心跳，保持用户在线状态
setInterval(async () => {
const token = getToken();
if (!token) return;
try {
await fetch('/api/auth/heartbeat', {
headers: {
'X-API-Key': 'your_api_key',
'X-User-Token': token
}
});
} catch (error) {
console.error('心跳失败:', error);
}
}, 5 * 60 * 1000); // 每5分钟一次4. 微信小程序登录示例
// 微信小程序登录
wx.login({
success: async (res) => {
if (res.code) {
try {
const result = await apiRequest('/api/wechat/auth', {
method: 'POST',
body: JSON.stringify({
code: res.code
})
});
// 保存Token
saveToken(result.token, result.expires_at);
// 跳转到首页
wx.switchTab({ url: '/pages/index/index' });
} catch (error) {
wx.showToast({
title: '登录失败',
icon: 'none'
});
}
}
}
});5. Unity C# 示例
using UnityEngine;
using UnityEngine.Networking;
using System.Collections;
using System.Text;
public class APIClient : MonoBehaviour
{
private string baseUrl = "https://your-domain.com/api";
private string apiKey = "your_api_key";
private string userToken;
// 用户注册
public IEnumerator Register(string account, string password)
{
var data = new {
account = account,
password = password
};
string jsonData = JsonUtility.ToJson(data);
using (UnityWebRequest request = new UnityWebRequest(baseUrl + "/auth/register", "POST"))
{
byte[] bodyRaw = Encoding.UTF8.GetBytes(jsonData);
request.uploadHandler = new UploadHandlerRaw(bodyRaw);
request.downloadHandler = new DownloadHandlerBuffer();
request.SetRequestHeader("Content-Type", "application/json");
request.SetRequestHeader("X-API-Key", apiKey);
yield return request.SendWebRequest();
if (request.result == UnityWebRequest.Result.Success)
{
string response = request.downloadHandler.text;
Debug.Log("注册成功: " + response);
// 解析响应，保存token
}
else
{
Debug.LogError("注册失败: " + request.error);
}
}
}
// 用户登录
public IEnumerator Login(string account, string password)
{
var data = new {
account = account,
password = password,
include_user_info = true,
include_user_data = true
};
string jsonData = JsonUtility.ToJson(data);
using (UnityWebRequest request = new UnityWebRequest(baseUrl + "/auth/login", "POST"))
{
byte[] bodyRaw = Encoding.UTF8.GetBytes(jsonData);
request.uploadHandler = new UploadHandlerRaw(bodyRaw);
request.downloadHandler = new DownloadHandlerBuffer();
request.SetRequestHeader("Content-Type", "application/json");
request.SetRequestHeader("X-API-Key", apiKey);
yield return request.SendWebRequest();
if (request.result == UnityWebRequest.Result.Success)
{
string response = request.downloadHandler.text;
Debug.Log("登录成功: " + response);
// 解析响应，保存token
}
else
{
Debug.LogError("登录失败: " + request.error);
}
}
}
// 获取用户数据
public IEnumerator GetUserData()
{
using (UnityWebRequest request = UnityWebRequest.Get(baseUrl + "/user/data"))
{
request.SetRequestHeader("X-API-Key", apiKey);
request.SetRequestHeader("X-User-Token", userToken);
yield return request.SendWebRequest();
if (request.result == UnityWebRequest.Result.Success)
{
string response = request.downloadHandler.text;
Debug.Log("用户数据: " + response);
}
else
{
Debug.LogError("获取失败: " + request.error);
}
}
}
// 更新用户数据
public IEnumerator UpdateUserData(string fieldName, string fieldValue)
{
var data = new {
[fieldName] = fieldValue
};
string jsonData = JsonUtility.ToJson(data);
using (UnityWebRequest request = new UnityWebRequest(baseUrl + "/user/data", "PUT"))
{
byte[] bodyRaw = Encoding.UTF8.GetBytes(jsonData);
request.uploadHandler = new UploadHandlerRaw(bodyRaw);
request.downloadHandler = new DownloadHandlerBuffer();
request.SetRequestHeader("Content-Type", "application/json");
request.SetRequestHeader("X-API-Key", apiKey);
request.SetRequestHeader("X-User-Token", userToken);
yield return request.SendWebRequest();
if (request.result == UnityWebRequest.Result.Success)
{
Debug.Log("更新成功");
}
else
{
Debug.LogError("更新失败: " + request.error);
}
}
}
}常见问题
Q1: Token过期了怎么办？
A: Token过期后需要重新登录获取新的Token。建议在客户端检查Token过期时间，提前重新登录。
Q2: 如何处理并发请求？
A: 系统支持并发请求，但建议控制请求频率，避免触发频率限制。
Q3: 数据加密会影响性能吗？
A: 加密会增加少量计算开销，但影响很小。如果对性能要求极高，可以只对敏感数据启用加密。
Q4: 如何调试API？
A: 可以使用Postman、curl等工具测试API。后台提供完整的API日志，可以查看请求和响应详情。
Q5: 支持跨域请求吗？
A: 系统已配置CORS，支持跨域请求。
更新日志
v1.0.0 (2025-10-17)
- 初始版本发布
- 支持用户注册、登录、信息管理
- 支持微信小程序登录
- 支持自定义数据存储
- 支持数据加密
- 完整的API日志记录
文档版本: v1.0.0
最后更新: 2025-10-17