使用 Go Zero 开发 FPS 游戏后端接口文档
目录
使用 Go Zero 开发 FPS 游戏后端接口文档
一、用户管理微服务
1. 注册接口
2. 登录接口
3. 账号信息管理接口
二、游戏匹配微服务
1. 匹配算法接口
2. 匹配队列接口
三、游戏房间管理微服务
1. 房间创建接口
2. 房间加入接口
3. 房间状态管理接口
四、游戏逻辑处理微服务
1. 玩家操作处理接口
1. 玩家操作处理接口
2. 碰撞检测接口
3. 伤害计算接口
五、数据存储与管理微服务
1. 玩家数据存储接口
2. 游戏数据存储接口
错误码与异常处理
通用错误码
特定错误码
用户管理微服务
游戏匹配微服务
游戏房间管理微服务
游戏逻辑处理微服务
数据存储与管理微服务
接口调用规范
身份验证
请求频率限制
数据格式
异常处理
接口变更说明
兼容性变更
非兼容性变更
附录
数据字典
状态码映射表
一、用户管理微服务
1. 注册接口
- 接口名称：用户注册
- 接口地址：
/api/user/register - 请求方法：
POST - 请求头：
字段 类型 描述 Content-Type string application/json - 请求参数：
字段 类型 是否必填 描述 register_type string 是 注册类型，可选值： phone（手机号注册）、email（邮箱注册）account string 是 手机号或邮箱 password string 是 密码 verify_code string 是 验证码 - 响应参数：
字段 类型 描述 code int 状态码，200 表示成功，其他表示失败 message string 响应信息 user_id string 注册成功后的用户 ID - 示例请求：
{
"register_type": "phone",
"account": "13800138000",
"password": "123456",
"verify_code": "1234"
}
- 示例响应：
{
"code": 200,
"message": "注册成功",
"user_id": "123456"
}
2. 登录接口
- 接口名称：用户登录
- 接口地址：
/api/user/login - 请求方法：
POST - 请求头：
字段 类型 描述 Content-Type string application/json - 请求参数：
字段 类型 是否必填 描述 login_type string 是 登录类型，可选值： password（密码登录）、verify_code（验证码登录）、third_party（第三方登录）account string 是 手机号、邮箱或第三方账号标识 password string 否 密码，当 login_type为password时必填verify_code string 否 验证码，当 login_type为verify_code时必填third_party_type string 否 第三方平台类型，如 wechat、qq，当login_type为third_party时必填third_party_token string 否 第三方授权令牌，当 login_type为third_party时必填 - 响应参数：
字段 类型 描述 code int 状态码，200 表示成功，其他表示失败 message string 响应信息 user_id string 用户 ID token string 登录成功后的身份凭证 - 示例请求：
{
"login_type": "password",
"account": "13800138000",
"password": "123456"
}
- 示例响应：
{
"code": 200,
"message": "登录成功",
"user_id": "123456",
"token": "abcdef123456"
}
3. 账号信息管理接口
- 接口名称：查看 / 修改账号信息
- 接口地址：
/api/user/info - 请求方法：
GET（查看）、PUT（修改） - 请求头：
字段 类型 描述 Content-Type string application/jsonAuthorization string 登录后的身份凭证 - 请求参数（GET）：无
- 请求参数（PUT）：
字段 类型 是否必填 描述 nickname string 否 昵称 avatar string 否 头像链接 gender string 否 性别，可选值： male、femalegame_preferences object 否 游戏偏好设置，如 {"sound_effect": "high", "graphics_quality": "medium"} - 响应参数（GET）：
字段 类型 描述 code int 状态码，200 表示成功，其他表示失败 message string 响应信息 user_info object 用户信息，如 {"nickname": "玩家1", "avatar": "http://example.com/avatar.jpg", "gender": "male", "game_preferences": {"sound_effect": "high", "graphics_quality": "medium"}} - 响应参数（PUT）：
字段 类型 描述 code int 状态码，200 表示成功，其他表示失败 message string 响应信息 - 示例请求（GET）：无
- 示例响应（GET）：
{
"code": 200,
"message": "获取成功",
"user_info": {
"nickname": "玩家1",
"avatar": "http://example.com/avatar.jpg",
"gender": "male",
"game_preferences": {
"sound_effect": "high",
"graphics_quality": "medium"
}
}
}
- 示例请求（PUT）：
{
"nickname": "新昵称",
"game_preferences": {
"sound_effect": "low"
}
}
- 示例响应（PUT）：
{
"code": 200,
"message": "修改成功"
}
二、游戏匹配微服务
1. 匹配算法接口
- 接口名称：玩家匹配
- 接口地址：
/api/match/start - 请求方法：
POST - 请求头：
字段 类型 描述 Content-Type string application/jsonAuthorization string 登录后的身份凭证 - 请求参数：
字段 类型 是否必填 描述 user_id string 是 用户 ID level int 是 玩家等级 rank string 是 玩家段位，如 bronze、silver等history_record object 是 玩家历史战绩，如 {"win_count": 10, "lose_count": 5} - 响应参数：
字段 类型 描述 code int 状态码，200 表示成功，其他表示失败 message string 响应信息 match_result object 匹配结果，如 {"matched": true, "opponent_id": "654321", "room_id": "987654"} - 示例请求：
{
"user_id": "123456",
"level": 10,
"rank": "silver",
"history_record": {
"win_count": 10,
"lose_count": 5
}
}
- 示例响应：
{
"code": 200,
"message": "匹配成功",
"match_result": {
"matched": true,
"opponent_id": "654321",
"room_id": "987654"
}
}
2. 匹配队列接口
- 接口名称：加入 / 退出匹配队列
- 接口地址：
/api/match/queue - 请求方法：
POST（加入）、DELETE（退出） - 请求头：
字段 类型 描述 Content-Type string application/jsonAuthorization string 登录后的身份凭证 - 请求参数（POST）：
字段 类型 是否必填 描述 user_id string 是 用户 ID - 请求参数（DELETE）：
字段 类型 是否必填 描述 user_id string 是 用户 ID - 响应参数（POST）：
字段 类型 描述 code int 状态码，200 表示成功，其他表示失败 message string 响应信息 queue_progress int 排队进度，0 - 100 estimated_wait_time int 预计等待时间（秒） - 响应参数（DELETE）：
字段 类型 描述 code int 状态码，200 表示成功，其他表示失败 message string 响应信息 - 示例请求（POST）：
{
"user_id": "123456"
}
- 示例响应（POST）：
{
"code": 200,
"message": "加入队列成功",
"queue_progress": 20,
"estimated_wait_time": 60
}
- 示例请求（DELETE）：
{
"user_id": "123456"
}
- 示例响应（DELETE）：
{
"code": 200,
"message": "退出队列成功"
}
三、游戏房间管理微服务
1. 房间创建接口
- 接口名称：创建游戏房间
- 接口地址：
/api/room/create - 请求方法：
POST - 请求头：
字段 类型 描述 Content-Type string application/jsonAuthorization string 登录后的身份凭证 - 请求参数：
字段 类型 是否必填 描述 user_id string 是 用户 ID map_name string 是 地图名称，如 desert_map、city_map等game_mode string 是 游戏模式，如 classic（经典对战）、team_battle（团队竞赛）等max_players int 是 房间最大人数 allow_spectators boolean 是 是否允许观战 - 响应参数：
字段 类型 描述 code int 状态码，200 表示成功，其他表示失败 message string 响应信息 room_id string 创建成功后的房间 ID - 示例请求：
{
"user_id": "123456",
"map_name": "desert_map",
"game_mode": "classic",
"max_players": 10,
"allow_spectators": true
}
- 示例响应：
{
"code": 200,
"message": "房间创建成功",
"room_id": "987654"
}
2. 房间加入接口
- 接口名称：加入游戏房间
- 接口地址：
/api/room/join - 请求方法：
POST - 请求头：
字段 类型 描述 Content-Type string application/jsonAuthorization string 登录后的身份凭证 - 请求参数：
字段 类型 是否必填 描述 user_id string 是 用户 ID room_id string 是 房间 ID - 响应参数：
字段 类型 描述 code int 状态码，200 表示成功，其他表示失败 message string 响应信息 - 示例请求：
{
"user_id": "123456",
"room_id": "987654"
}
- 示例响应：
{
"code": 200,
"message": "加入房间成功"
}
3. 房间状态管理接口
- 接口名称：获取 / 更新房间状态
- 接口地址：
/api/room/status - 请求方法：
GET（获取）、PUT（更新） - 请求头：
字段 类型 描述 Content-Type string application/jsonAuthorization string 登录后的身份凭证 - 请求参数（GET）：
字段 类型 是否必填 描述 room_id string 是 房间 ID - 请求参数（PUT）：
字段 类型 是否必填 描述 room_id string 是 房间 ID status object 是 房间状态信息，如 {"player_count": 5, "game_started": false, "remaining_time": 60} - 响应参数（GET）：
字段 类型 描述 code int 状态码，200 表示成功，其他表示失败 message string 响应信息 room_status object 房间状态信息，如 {"player_count": 5, "game_started": false, "remaining_time": 60} - 响应参数（PUT）：
字段 类型 描述 code int 状态码，200 表示成功，其他表示失败 message string 响应信息 - 示例请求（GET）：
{
"room_id": "987654"
}
- 示例响应（GET）：
{
"code": 200,
"message": "获取成功",
"room_status": {
"player_count": 5,
"game_started": false,
"remaining_time": 60
}
}
- 示例请求（PUT）：
{
"room_id": "987654",
"status": {
"player_count": 6,
"game_started": false,
"remaining_time": 50
}
}
- 示例响应（PUT）：
{
"code": 200,
"message": "更新成功"
}
四、游戏逻辑处理微服务
1. 玩家操作处理接口
- 接口名称：处理玩家操作
- 接口地址：
/api/game/action - 请求方法：
POST - 请求头：
| 字段 | 类型 | 描述 |
继续
1. 玩家操作处理接口
- 接口名称：处理玩家操作
- 接口地址：
/api/game/action - 请求方法：
POST - 请求头：
字段 类型 描述 Content-Type string application/jsonAuthorization string 登录后的身份凭证 - 请求参数：
字段 类型 是否必填 描述 user_id string 是 用户 ID room_id string 是 房间 ID action_type string 是 操作类型，如 move（移动）、shoot（射击）、jump（跳跃）、reload（换弹）、use_skill（使用技能）等action_data object 是 操作相关数据，根据操作类型不同而不同。例如， move操作可能包含{"direction": "forward", "speed": 5}；shoot操作可能包含{"weapon_id": "pistol_01", "target_position": [10, 20, 30]} - 响应参数：
字段 类型 描述 code int 状态码，200 表示成功，其他表示失败 message string 响应信息 action_result object 操作处理结果，如 {"success": true, "new_position": [12, 22, 32]}（移动操作） 或{"success": true, "hit": false}（射击操作） - 示例请求：
{
"user_id": "123456",
"room_id": "987654",
"action_type": "move",
"action_data": {
"direction": "forward",
"speed": 5
}
}
- 示例响应：
{
"code": 200,
"message": "操作处理成功",
"action_result": {
"success": true,
"new_position": [12, 22, 32]
}
}
2. 碰撞检测接口
- 接口名称：碰撞检测
- 接口地址：
/api/game/collision - 请求方法：
POST - 请求头：
字段 类型 描述 Content-Type string application/jsonAuthorization string 登录后的身份凭证 - 请求参数：
字段 类型 是否必填 描述 room_id string 是 房间 ID objects array 是 参与碰撞检测的物体列表，每个物体包含 object_id（物体 ID）、position（位置坐标，如[10, 20, 30]）、size（物体大小，如[2, 2, 2]）等信息，例如[{"object_id": "player_01", "position": [10, 20, 30], "size": [2, 2, 2]}, {"object_id": "bullet_01", "position": [12, 22, 32], "size": [0.1, 0.1, 0.1]}] - 响应参数：
字段 类型 描述 code int 状态码，200 表示成功，其他表示失败 message string 响应信息 collision_result array 碰撞检测结果，每个元素是一个碰撞对，如 [{"object1_id": "player_01", "object2_id": "bullet_01", "collided": true}] - 示例请求：
{
"room_id": "987654",
"objects": [
{
"object_id": "player_01",
"position": [10, 20, 30],
"size": [2, 2, 2]
},
{
"object_id": "bullet_01",
"position": [12, 22, 32],
"size": [0.1, 0.1, 0.1]
}
]
}
- 示例响应：
{
"code": 200,
"message": "碰撞检测成功",
"collision_result": [
{
"object1_id": "player_01",
"object2_id": "bullet_01",
"collided": true
}
]
}
3. 伤害计算接口
- 接口名称：伤害计算
- 接口地址：
/api/game/damage - 请求方法：
POST - 请求头：
字段 类型 描述 Content-Type string application/jsonAuthorization string 登录后的身份凭证 - 请求参数：
字段 类型 是否必填 描述 attacker_id string 是 攻击者用户 ID victim_id string 是 受害者用户 ID weapon_id string 是 武器 ID，如 rifle_01、shotgun_02等ammo_type string 是 弹药类型，如 7.62mm、12gauge等distance float 是 射击距离 hit_part string 是 击中部位，如 head、chest、leg等 - 响应参数：
字段 类型 描述 code int 状态码，200 表示成功，其他表示失败 message string 响应信息 damage_value float 计算得出的伤害值 - 示例请求：
{
"attacker_id": "123456",
"victim_id": "654321",
"weapon_id": "rifle_01",
"ammo_type": "7.62mm",
"distance": 20.0,
"hit_part": "chest"
}
- 示例响应：
{
"code": 200,
"message": "伤害计算成功",
"damage_value": 30.0
}
五、数据存储与管理微服务
1. 玩家数据存储接口
- 接口名称：存储 / 读取玩家数据
- 接口地址：
/api/data/player - 请求方法：
POST（存储）、GET（读取） - 请求头：
字段 类型 描述 Content-Type string application/jsonAuthorization string 登录后的身份凭证 - 请求参数（POST）：
字段 类型 是否必填 描述 user_id string 是 用户 ID data object 是 玩家数据，如 {"account_info": {"nickname": "玩家1", "email": "test@example.com"}, "game_records": [{"match_id": "111111", "kills": 5, "deaths": 3}], "achievements": ["first_blood"], "items": ["pistol_01"]} - 请求参数（GET）：
字段 类型 是否必填 描述 user_id string 是 用户 ID - 响应参数（POST）：
字段 类型 描述 code int 状态码，200 表示成功，其他表示失败 message string 响应信息 - 响应参数（GET）：
字段 类型 描述 code int 状态码，200 表示成功，其他表示失败 message string 响应信息 player_data object 玩家数据，格式同 data参数 - 示例请求（POST）：
{
"user_id": "123456",
"data": {
"account_info": {
"nickname": "玩家1",
"email": "test@example.com"
},
"game_records": [
{
"match_id": "111111",
"kills": 5,
"deaths": 3
}
],
"achievements": [
"first_blood"
],
"items": [
"pistol_01"
]
}
}
- 示例响应（POST）：
{
"code": 200,
"message": "玩家数据存储成功"
}
- 示例请求（GET）：
{
"user_id": "123456"
}
- 示例响应（GET）：
{
"code": 200,
"message": "玩家数据读取成功",
"player_data": {
"account_info": {
"nickname": "玩家1",
"email": "test@example.com"
},
"game_records": [
{
"match_id": "111111",
"kills": 5,
"deaths": 3
}
],
"achievements": [
"first_blood"
],
"items": [
"pistol_01"
]
}
}
2. 游戏数据存储接口
- 接口名称：存储 / 查询游戏数据
- 接口地址：
/api/data/game - 请求方法：
POST（存储）、GET（查询） - 请求头：
字段 类型 描述 Content-Type string application/jsonAuthorization string 登录后的身份凭证 - 请求参数（POST）：
字段 类型 是否必填 描述 match_id string 是 比赛 ID game_data object 是 游戏数据，如 {"players": [{"user_id": "123456", "kills": 10, "deaths": 5}, {"user_id": "654321", "kills": 8, "deaths": 7}], "match_result": "team1_win", "duration": 1800} - 请求参数（GET）：
字段 类型 是否必填 描述 match_id string 是 比赛 ID - 响应参数（POST）：
字段 类型 描述 code int 状态码，200 表示成功，其他表示失败 message string 响应信息 - 响应参数（GET）：
字段 类型 描述 code int 状态码，200 表示成功，其他表示失败 message string 响应信息 game_data object 游戏数据，格式同 game_data参数 - 示例请求（POST）：
{
"match_id": "222222",
"game_data": {
"players": [
{
"user_id": "123456",
"kills": 10,
"deaths": 5
},
{
"user_id": "654321",
"kills": 8,
"deaths": 7
}
],
"match_result": "team1_win",
"duration": 1800
}
}
- 示例响应（POST）：
{
"code": 200,
"message": "游戏数据存储成功"
}
- 示例请求（GET）：
{
"match_id": "222222"
}
- 示例响应（GET）：
{
"code": 200,
"message": "游戏数据查询成功",
"game_data": {
"players": [
{
"user_id": "123456",
"kills": 10,
"deaths": 5
},
{
"user_id": "654321",
"kills": 8,
"deaths": 7
}
],
"match_result": "team1_win",
"duration": 1800
}
}
错误码与异常处理
通用错误码
| 错误码 | 描述 |
|---|---|
| 400 | 无效的请求参数，可能是请求体格式错误、缺少必要参数等 |
| 401 | 未授权，缺少有效的身份凭证（如未提供 Authorization 头或凭证无效） |
| 403 | 禁止访问，用户没有权限执行该操作 |
| 404 | 请求的资源不存在，如接口地址错误、房间 ID 不存在等 |
| 500 | 服务器内部错误，可能是数据库连接失败、代码逻辑异常等 |
特定错误码
用户管理微服务
| 错误码 | 描述 |
|---|---|
| 1001 | 注册失败，可能是账号已存在、验证码错误等 |
| 1002 | 登录失败，可能是账号或密码错误、验证码错误、第三方授权失败等 |
| 1003 | 修改账号信息失败，可能是参数格式错误、数据库更新失败等 |
游戏匹配微服务
| 错误码 | 描述 |
|---|---|
| 2001 | 匹配失败，可能是当前没有合适的对手、匹配算法出错等 |
| 2002 | 加入匹配队列失败，可能是用户已在队列中、服务器队列已满等 |
| 2003 | 退出匹配队列失败，可能是用户不在队列中 |
游戏房间管理微服务
| 错误码 | 描述 |
|---|---|
| 3001 | 房间创建失败，可能是参数错误、服务器资源不足等 |
| 3002 | 加入房间失败，可能是房间已满、房间已开始游戏、不符合房间规则等 |
| 3003 | 更新房间状态失败，可能是参数错误、数据库更新失败等 |
游戏逻辑处理微服务
| 错误码 | 描述 |
|---|---|
| 4001 | 玩家操作处理失败，可能是操作类型不支持、操作数据格式错误等 |
| 4002 | 碰撞检测失败，可能是物体数据格式错误、检测算法出错等 |
| 4003 | 伤害计算失败，可能是武器或弹药信息错误、参数超出范围等 |
数据存储与管理微服务
| 错误码 | 描述 |
|---|---|
| 5001 | 玩家数据存储失败，可能是数据库连接失败、数据格式错误等 |
| 5002 | 玩家数据读取失败，可能是用户 ID 不存在、数据库查询失败等 |
| 5003 | 游戏数据存储失败，可能是数据库连接失败、数据格式错误等 |
| 5004 | 游戏数据查询失败，可能是比赛 ID 不存在、数据库查询失败等 |
接口调用规范
身份验证
所有需要身份验证的接口都必须在请求头中包含 Authorization 字段，其值为登录时返回的 token。例如：
Authorization: abcdef123456
请求频率限制
为了防止恶意攻击和资源滥用，部分接口会有请求频率限制。例如，登录接口每分钟最多允许尝试 5 次，匹配接口每 10 秒最多允许调用 1 次。当请求频率超过限制时，接口将返回 429 错误码（Too Many Requests），并在响应头中包含 Retry-After 字段，指示客户端需要等待的时间（秒）。
数据格式
请求和响应的数据格式均为 JSON。请求体中的参数名和值应符合接口文档的定义，响应体中的字段也应按照文档规定的格式返回。
异常处理
客户端在调用接口时，应根据返回的状态码和错误信息进行相应的处理。对于 500 错误码，客户端可以选择重试请求；对于 401 错误码，客户端应提示用户重新登录；对于其他错误码，客户端可以根据具体的错误描述向用户展示相应的提示信息。
接口变更说明
在项目开发和维护过程中，可能会对接口进行变更，包括接口地址、请求方法、请求参数、响应参数等。接口变更时，将遵循以下原则：
兼容性变更
对于不影响现有客户端正常使用的变更，如增加可选的请求参数、增加响应字段等，将在不改变接口地址和请求方法的前提下进行更新，并在接口文档中注明变更内容和变更时间。
非兼容性变更
对于会影响现有客户端正常使用的变更，如修改接口地址、请求方法、必填参数等，将提前发布变更通知，说明变更的原因、时间和影响范围，并提供相应的迁移指南。同时，会保留旧接口一段时间（如 1 个月），以便客户端有足够的时间进行升级。
附录
数据字典
| 字段 | 描述 | 取值范围 |
|---|---|---|
| register_type | 注册类型 | phone（手机号注册）、email（邮箱注册） |
| login_type | 登录类型 | password（密码登录）、verify_code（验证码登录）、third_party（第三方登录） |
| third_party_type | 第三方平台类型 | wechat（微信）、qq（QQ） |
| game_mode | 游戏模式 | classic（经典对战）、team_battle（团队竞赛）等 |
| action_type | 玩家操作类型 | move（移动）、shoot（射击）、jump（跳跃）、reload（换弹）、use_skill（使用技能）等 |
| hit_part | 击中部位 | head（头部）、chest（胸部）、leg（腿部）等 |
状态码映射表
| 状态码 | 含义 |
|---|---|
| 200 | 成功 |
| 400 | 无效请求 |
| 401 | 未授权 |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 429 | 请求频率过高 |
| 500 | 服务器内部错误 |
| 具体业务错误码 | 见上文特定错误码部分 |