web-rust-template-project/docs/api/endpoints/public.md

公开接口文档

本文档详细说明所有无需认证即可访问的 API 接口。

目录

• GET /health - 健康检查
• GET /info - 服务器信息
• POST /auth/register - 用户注册
• POST /auth/login - 用户登录
• POST /auth/refresh - 刷新 Token

---

GET /health

健康检查端点，用于检查服务是否正常运行。

请求

GET /health

请求参数：无

请求头：无特殊要求

响应

成功响应 (200)：

{
  "status": "ok"
}

或服务不可用时：

{
  "status": "unavailable"
}

示例

curl http://localhost:3000/health

错误码

错误码	说明
500	服务器内部错误

---

GET /info

获取服务器基本信息，包括应用名称、版本、状态等。

请求

GET /info

请求参数：无

请求头：无特殊要求

响应

成功响应 (200)：

{
  "name": "web-rust-template",
  "version": "0.1.0",
  "status": "running",
  "timestamp": 1704112800
}

字段说明

字段	类型	说明
name	string	应用名称
version	string	应用版本
status	string	运行状态
timestamp	number	当前时间戳（Unix 时间戳）

示例

curl http://localhost:3000/info

错误码

错误码	说明
500	服务器内部错误

---

POST /auth/register

创建新用户账户。注册成功后自动登录，返回 Access Token 和 Refresh Token。

请求

POST /auth/register
Content-Type: application/json

请求参数：

{
  "email": "user@example.com",
  "password": "password123"
}

字段说明

字段	类型	必填	说明
email	string	是	用户邮箱，必须是有效的邮箱格式
password	string	是	用户密码，建议长度至少 8 位

响应

成功响应 (200)：

{
  "code": 200,
  "message": "Success",
  "data": {
    "email": "user@example.com",
    "created_at": "2026-02-13T12:00:00.000Z",
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

响应字段说明

字段	类型	说明
email	string	用户邮箱
created_at	string	账号创建时间（ISO 8601 格式）
access_token	string	Access Token，有效期 15 分钟
refresh_token	string	Refresh Token，有效期 7 天

示例

curl -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password123"
  }'

错误码

错误码	说明
400	请求参数错误（邮箱格式错误、密码长度不够）
409	邮箱已被注册
500	服务器内部错误

注意事项

• 邮箱地址将作为用户的唯一标识符
• 密码会使用 Argon2 算法进行哈希存储
• 注册成功后会自动生成 Access Token 和 Refresh Token
• Refresh Token 会存储在 Redis 中，用于后续刷新 Token

---

POST /auth/login

用户登录。验证成功后返回 Access Token 和 Refresh Token。

请求

POST /auth/login
Content-Type: application/json

请求参数：

{
  "email": "user@example.com",
  "password": "password123"
}

字段说明

字段	类型	必填	说明
email	string	是	用户邮箱
password	string	是	用户密码

响应

成功响应 (200)：

{
  "code": 200,
  "message": "Success",
  "data": {
    "id": "1234567890",
    "email": "user@example.com",
    "created_at": "2026-02-13T12:00:00.000Z",
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

响应字段说明

字段	类型	说明
id	string	用户 ID（10 位数字）
email	string	用户邮箱
created_at	string	账号创建时间（ISO 8601 格式）
access_token	string	Access Token，有效期 15 分钟
refresh_token	string	Refresh Token，有效期 7 天

示例

curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password123"
  }'

错误码

错误码	说明
400	请求参数错误
401	邮箱或密码错误
500	服务器内部错误

注意事项

• 登录失败不会返回具体的错误信息（如"邮箱不存在"或"密码错误"），统一返回"邮箱或密码错误"
• 密码错误次数过多可能会被临时限制（取决于具体实现）
• 登录成功后会生成新的 Token 对，旧的 Token 会失效

---

POST /auth/refresh

使用 Refresh Token 获取新的 Access Token 和 Refresh Token。

请求

POST /auth/refresh
Content-Type: application/json

请求参数：

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

字段说明

字段	类型	必填	说明
refresh_token	string	是	Refresh Token

响应

成功响应 (200)：

{
  "code": 200,
  "message": "Success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

响应字段说明

字段	类型	说明
access_token	string	新的 Access Token，有效期 15 分钟
refresh_token	string	新的 Refresh Token，有效期 7 天

示例

curl -X POST http://localhost:3000/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

错误码

错误码	说明
400	请求参数错误
401	Refresh Token 无效或已过期
500	服务器内部错误

注意事项

• 每次刷新会生成新的 Refresh Token，旧的 Refresh Token 会立即失效
• Refresh Token 只能使用一次，重复使用会返回错误
• Refresh Token 有效期为 7 天，过期后需要重新登录
• Refresh Token 存储在 Redis 中，服务器重启不会丢失（如果 Redis 持久化配置正确）

Token 刷新策略建议

前端实现建议：

1. 在每次 API 请求失败（401 错误）时尝试刷新 Token
2. 刷新成功后重试原请求
3. 刷新失败则跳转到登录页
4. 不要在 Token 即将过期时主动刷新，而是在使用时检查有效性

查看 前端集成示例 了解完整的实现代码。

---

相关文档

• 受保护接口文档 - 需要认证的接口说明
• 认证机制详解 - 完整的认证流程说明
• API 概览 - 所有接口快速索引
• 前端集成示例 - 前端集成代码示例

---

提示：建议使用 Postman、Insomnia 或类似工具测试 API 接口。