【文字三国志：第四篇】天命重构，后端 API 设计文档

第一章：整体架构

1.1 设计理念

本项目的后端 API 采用Next.js 13 App Router的Route Handlers能力构建。你可以把它理解为：每个 API 端点都是一个独立的“小服务”，它们共同组成了一个完整的游戏后端。

所有业务接口都统一放在/api/game这个“大门”下，这样做的好处是：

• 路径清晰：一眼就能看出这是游戏相关的功能
• 便于管理：相关的功能模块集中存放
• 易于扩展：新增功能只需在game下新建目录
  

1.2 技术架构图

1.3 目录结构说明

src/app/api/game/ ├── start/ # 游戏初始化 │ └── route.ts ├── action/ # 玩家动作 │ └── route.ts ├── combat/ # 战斗日志 │ └── route.ts ├── achievements/ # 成就系统 │ └── route.ts ├── alliances/ # 联盟系统 │ └── route.ts ├── policy/ # 政策系统 │ └── route.ts └── events/ # 实时事件 └── route.ts

每个route.ts文件都保持精简，只做三件事：校验身份 → 校验参数 → 调用核心逻辑。

第二章：通用约定规范

2.1 HTTP 方法使用规范

2.2 统一的返回格式

所有的 API 都遵循相同的“包装格式”，就像快递包裹一样：

// 成功时{success:true,data:{/* 具体的业务数据 */}}// 失败时{success:false,error:"具体的错误信息"}

2.3 鉴权机制