API 文档

阿探(AtSeeker) Services API 参考文档，包含所有接口的详细说明

Passport Service

用户认证服务

POST/auth/v1/register

用户注册

创建新用户账户

参数说明

参数名	类型	必填	说明
nickname	string	必填	用户昵称(1-50字符)
password	string	必填	密码(6-100字符)
contact_type	string	必填	联系方式类型: phone 或 email
contact	string	必填	手机号或邮箱
captcha	string	可选	验证码(可选)
app_id	string	必填	应用ID

请求示例

POST /auth/v1/register
Content-Type: application/json
Authorization: Bearer <api_key>

{
  "nickname": "张三",
  "password": "password123",
  "contact_type": "email",
  "contact": "zhangsan@example.com",
  "app_id": "your_app_id"
}

响应示例

{
  "userId": "0f3b7a6e-1c2d-4a5b-9e8f-1234567890ab",
  "nickname": "张三",
  "email": "zhangsan@example.com",
  "app_id": "your_app_id",
  "is_active": true,
  "is_registered": true,
  "created_at": "2024-12-05T10:00:00Z"
}

POST/auth/v1/login

用户登录

使用手机号/邮箱和密码登录

参数说明

参数名	类型	必填	说明
contact_type	string	必填	联系方式类型: phone 或 email
contact	string	必填	手机号或邮箱
password	string	必填	密码
app_id	string	必填	应用ID

请求示例

POST /auth/v1/login
Content-Type: application/json
Authorization: Bearer <api_key>

{
  "contact_type": "email",
  "contact": "zhangsan@example.com",
  "password": "password123",
  "app_id": "your_app_id"
}

响应示例

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 86400,
  "token_type": "Bearer"
}

GET/auth/v1/users/{userId}

获取用户信息

根据用户ID获取用户详细信息

参数说明

参数名	类型	必填	说明
userId	string	必填	用户ID（字符串UUID）

请求示例

GET /auth/v1/users/12345
Authorization: Bearer <api_key>

响应示例

{
  "userId": "0f3b7a6e-1c2d-4a5b-9e8f-1234567890ab",
  "nickname": "张三",
  "email": "zhangsan@example.com",
  "avatar": "https://cdn.example.com/avatar.jpg",
  "app_id": "your_app_id",
  "is_active": true,
  "is_registered": true,
  "created_at": "2024-12-05T10:00:00Z"
}

POST/auth/v1/token/validate

验证Token

验证访问令牌的有效性并获取用户信息

参数说明

参数名	类型	必填	说明
token	string	必填	访问令牌

请求示例

POST /auth/v1/token/validate
Content-Type: application/json
Authorization: Bearer <api_key>

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

响应示例

{
  "userId": "0f3b7a6e-1c2d-4a5b-9e8f-1234567890ab",
  "role": "user"
}

POST/auth/v1/captcha

发送验证码

向手机号或邮箱发送验证码

参数说明

参数名	类型	必填	说明
contact_type	string	必填	联系方式类型: phone 或 email
contact	string	必填	手机号或邮箱
scene	string	必填	场景: captcha_register, captcha_login, captcha_reset_password

请求示例

POST /auth/v1/captcha
Content-Type: application/json
Authorization: Bearer <api_key>

{
  "contact_type": "email",
  "contact": "zhangsan@example.com",
  "scene": "captcha_register"
}

响应示例

{}

PUT/auth/v1/users/{userId}

更新用户信息

更新用户的个人资料，包括昵称、头像、个性签名等

参数说明

参数名	类型	必填	说明
userId	string	必填	用户ID（字符串UUID）
nickname	string	可选	昵称
avatar	string	可选	头像URL（通过 Asset Service 上传后获取）
signature	string	可选	个性签名

请求示例

PUT /auth/v1/users/12345
Content-Type: application/json
Authorization: Bearer <api_key>

{
  "userId": "0f3b7a6e-1c2d-4a5b-9e8f-1234567890ab",
  "nickname": "新昵称",
  "avatar": "https://cdn.atseeker.com/abc123-def456-ghi789"
}

响应示例

{
  "userId": "0f3b7a6e-1c2d-4a5b-9e8f-1234567890ab",
  "nickname": "新昵称",
  "avatar": "https://cdn.atseeker.com/abc123-def456-ghi789",
  "email": "zhangsan@example.com",
  "is_active": true,
  "created_at": "2024-12-05T10:00:00Z"
}

使用场景

用户头像上传

上传用户头像图片，然后更新用户信息

// 1. 先上传头像图片到 Asset Service
const formData = new FormData();
formData.append('file', avatarFile);

const uploadRes = await fetch('/asset/v1/files/upload', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${apiKey}` },
  body: formData
});
const { file_id, url } = uploadRes.data;

// 2. 更新用户信息，使用返回的 url 作为头像
const updateRes = await fetch(`/auth/v1/users/${userId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    userId: userId,
    avatar: url  // 使用 Asset Service 返回的 URL
  })
});

// 3. 头像已更新，前端可以直接使用 url 显示