快速开始

本篇帮助你在几分钟内完成 WPF API 的首次调用：了解基础域名、鉴权方式与统一响应格式，并跑通一个完整的 注册 → 登录 → 调用业务接口 流程。

一、基础域名

所有接口均基于统一的生产域名访问：

环境	地址
生产环境	`https://devapi.fengshengshou.com`

后文示例统一使用该域名。请求路径均以 /api/ 开头，例如 https://devapi.fengshengshou.com/api/auth/login。

二、鉴权方式

WPF API 采用 Bearer Token 鉴权。除注册、登录等公开接口外，所有接口都必须在请求头中携带合法 Token：

Authorization: Bearer <access_token>
Accept: application/json
Content-Type: application/json

如何获取 Token

方式	接口	说明
注册	`POST /api/auth/register`	首次使用，创建账号
登录	`POST /api/auth/login`	已有账号，换取 Token

注册或登录成功后，响应 data.access_token 即为后续所有接口的凭证，请在客户端妥善保存。

三、统一响应格式

所有接口返回统一的 JSON 结构，通过 code 字段判断业务结果：

场景	格式
成功	`{ "code": 0, "message": "success", "data": {...} }`
失败	`{ "code": <错误码>, "message": "<错误信息>", "data": null }`

code = 0 表示业务成功，data 携带返回数据。
code != 0 表示业务阻断，message 说明原因，data 通常为 null。
HTTP 状态码用于表达传输层结果，业务判断请以 code 为准。完整对照见错误码。

四、第一次调用

以下示例演示从登录到调用业务接口的最小闭环。

1. 登录换取 Token

curl -X POST https://devapi.fengshengshou.com/api/auth/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"username":"your_username","password":"your_password"}'

成功响应（节选）：

{
  "code": 0,
  "message": "登录成功",
  "data": {
    "access_token": "your_token_here",
    "token_type": "Bearer",
    "expires_in": 7200,
    "user": {
      "id": 461,
      "username": "your_username",
      "name": "示例用户"
    }
  }
}

保存 data.access_token 与 data.user.id，后续接口都会用到。

2. 携带 Token 调用业务接口

以创建房间 Seed 为例：

curl -X POST https://devapi.fengshengshou.com/api/gm/seed/create \
  -H "Authorization: Bearer your_token_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"user_id":461,"scene_name":"Level_01_Base"}'

成功响应：

{
  "code": 0,
  "message": "创建成功",
  "data": {
    "seed_code": "9Q6JZ6",
    "created_at": "2026-06-07 11:08:01"
  }
}

3. 处理失败响应

当 Token 缺失或过期时：

{
  "code": 401,
  "message": "登录状态已失效，请重新登录",
  "data": null
}

此时应重新执行登录流程获取新的 Token。

五、接入建议

统一封装请求层：集中处理 Authorization 头注入与 code 判断，避免每个接口重复编写。
Token 过期重试：捕获 code = 401 后自动触发重新登录，再重放原请求。
参数校验前置：必填字段缺失会返回 422，建议在客户端提交前做基础校验。
按模块查阅：各业务模块的接口清单与数据结构见 API 概览。