321 lines
12 KiB
Markdown
321 lines
12 KiB
Markdown
# 后端接口对接规范
|
||
|
||
## 1. 目标
|
||
|
||
本文档用于 Aslan Flutter 项目后续与后端接口对接时统一协作边界、接口事实来源、前端落地位置、记录格式和问题流转方式。
|
||
|
||
核心原则：
|
||
|
||
- 前端可以只读查看后端代码、接口文档和契约，用于理解接口、字段、错误码、鉴权和业务边界。
|
||
- 前端绝对不能修改后端仓库中的任何代码、文档、配置、生成文件、SQL、资源或测试。
|
||
- 如果发现后端接口、字段、错误码或业务逻辑需要调整，只能整理建议和证据，由用户协调后端处理。
|
||
- 对接接口时禁止本地假数据兜底；接口报错、空数据、权限失败、字段缺失都必须按真实状态处理，不能用本地 mock 数据伪装成接口成功。
|
||
|
||
---
|
||
|
||
## 2. 当前前端项目事实
|
||
|
||
当前 Flutter 项目路径：
|
||
|
||
```text
|
||
/Users/pinpaibu/flutter_code/aslan-flutter
|
||
```
|
||
|
||
项目名与包：
|
||
|
||
- 应用名：`Aslan`
|
||
- Flutter package import 前缀：`package:aslan/...`
|
||
- 当前配置入口：`lib/chatvibe_core/config/app_config.dart`
|
||
- 当前默认配置：`Variant1Config`
|
||
- 当前 API Host：`https://api.atuchat.com/`
|
||
- 当前图片 Host：`https://img.atuchat.com/`
|
||
|
||
主要前端分层：
|
||
|
||
- `lib/chatvibe_core/`：配置、常量、路由、通用工具。
|
||
- `lib/chatvibe_data/`：数据层实现、本地存储、网络请求、仓库实现。
|
||
- `lib/chatvibe_domain/`：仓库接口、请求模型、响应模型和领域模型。
|
||
- `lib/chatvibe_features/`：按业务功能组织的页面、状态和交互逻辑。
|
||
- `lib/chatvibe_managers/`：跨页面复用的管理器。
|
||
- `lib/chatvibe_ui/`：公共 UI 组件、主题和通用 widgets。
|
||
- `local_packages/`：项目内维护的本地 Flutter 插件，不能随意替换为 pub.dev 原版。
|
||
|
||
---
|
||
|
||
## 3. 后端代码位置
|
||
|
||
服务端代码项目名称：`likei-services`。
|
||
|
||
当前本机后端仓库路径：
|
||
|
||
```text
|
||
/Users/pinpaibu/server_code/likei-services
|
||
```
|
||
|
||
已确认的后端结构：
|
||
|
||
- `rc-gateway/`：服务网关，客户端接口对接优先看这里。
|
||
- `rc-auth/`：认证服务。
|
||
- `rc-service/rc-service-wallet/`：钱包服务。
|
||
- `rc-service/rc-service-live/`：直播 / 语音房相关服务。
|
||
- `rc-service/rc-service-order/`：订单服务。
|
||
- `rc-service/rc-service-other/`：其他业务服务。
|
||
- `rc-service/rc-service-external/`：外部能力对接服务。
|
||
- `rc-service/rc-service-console/`：后台运营服务。
|
||
- `rc-service/rc-inner-api/`：内部服务 API / DTO 契约。
|
||
- `rc-common-business/`：通用业务组件、DTO、MQ、核心能力。
|
||
- `rc-register/`：注册配置中心。
|
||
- `rc-scheduling/`：调度中心。
|
||
- `rc-service-game/`：游戏服务。
|
||
- `claude/`、`reports/`：后端辅助资料或报告，按需只读参考。
|
||
|
||
```text
|
||
后端仓库类型：Java / Maven 多模块服务
|
||
```
|
||
|
||
说明：
|
||
|
||
- 后端代码仅用于接口 API 参考。
|
||
- 不要修改服务端任何代码。
|
||
- 如果服务端需要增加接口或者存在 bug，只能提出建议和证据。
|
||
|
||
---
|
||
|
||
## 4. 后端代码只读红线
|
||
|
||
后续任何前端线程、AI 或开发者，进入后端路径时必须遵守：
|
||
|
||
- 只允许查看、搜索、摘录和分析后端代码。
|
||
- 禁止创建、修改、删除、移动、格式化后端仓库中的任何文件。
|
||
- 禁止对后端仓库使用 `apply_patch`、编辑器保存、`sed -i`、重定向写文件、脚本生成、批量替换等写入方式。
|
||
- 禁止运行会改动后端仓库文件的命令，例如格式化、依赖整理、代码生成、数据库迁移生成、OpenAPI 生成、mock 生成。
|
||
- 默认不在后端仓库执行构建、测试、启动、Docker、Makefile 或脚本命令；如果确实需要运行，必须先说明目的、可能产生的文件影响，并得到用户明确允许。
|
||
- 禁止提交、暂存、切分支、rebase、merge、pull、push 后端仓库。
|
||
- 禁止把前端对接需要的临时标记写入后端代码注释或文档。
|
||
|
||
允许的只读命令示例：
|
||
|
||
```text
|
||
ls
|
||
find
|
||
rg
|
||
sed -n
|
||
git status --short
|
||
git diff --stat
|
||
git show
|
||
git grep
|
||
```
|
||
|
||
如果命令可能产生缓存、日志、生成文件或配置变更，默认视为禁止。
|
||
|
||
---
|
||
|
||
## 5. 接口事实参考顺序
|
||
|
||
对接某个接口前，必须按以下顺序确认事实：
|
||
|
||
1. 先看后端接口文档或 OpenAPI，确认 HTTP path、method、请求体、响应体、鉴权要求和错误码描述。
|
||
2. 再看后端实际路由注册和 handler/controller，确认当前线上实现、参数解析、响应 envelope 和鉴权行为。
|
||
3. 如接口由内部服务 API、DTO、Feign/RPC 或其它内部契约支撑，再看对应契约，确认字段语义、枚举、默认值和跨服务约束。
|
||
4. 必要时查看后端 service/domain/storage 代码，只为理解业务规则和字段来源，不直接照搬内部实现到前端。
|
||
5. 最后再查看业务说明文档，用于确认流程边界、当前限制和后续计划。
|
||
|
||
当接口文档、handler、契约、业务文档之间不一致时：
|
||
|
||
- 以当前后端 handler/controller 实现作为“现状事实”记录。
|
||
- 同时把不一致点写入“待后端确认事项”。
|
||
- 前端不得自行修改后端文档或代码来消除不一致。
|
||
|
||
---
|
||
|
||
## 6. 当前 Flutter 网络层约定
|
||
|
||
网络入口：
|
||
|
||
- 全局请求实例：`lib/chatvibe_data/sources/remote/net/network_client.dart` 中的 `http`
|
||
- 通用请求基类：`lib/chatvibe_data/sources/remote/net/api.dart` 中的 `BaseNetworkClient`
|
||
- Dio 基础配置：`connectTimeout = 12s`，`receiveTimeout = 15s`
|
||
- 额外超时拦截：`TimeOutInterceptor.globalTimeoutSeconds = 15`
|
||
|
||
基础 URL：
|
||
|
||
- `NetworkClient.init()` 设置 `dio.options.baseUrl = ATGlobalConfig.apiHost`
|
||
- `ApiInterceptor.onRequest()` 每次请求会重新写入 `options.baseUrl = ATGlobalConfig.apiHost`
|
||
- `ATGlobalConfig.apiHost` 来自 `AppConfig.current.apiHost`
|
||
|
||
请求头：
|
||
|
||
- `req-lang`：当前语言。
|
||
- `req-imei`：设备 ID。
|
||
- `req-app-intel`：版本、build、机型、系统版本、渠道。
|
||
- `req-client`：`Android` 或 `iOS`。
|
||
- `req-sys-origin`：`origin` 与 `originChild`。
|
||
- `Authorization`：当本地 token 非空时发送 `Bearer <token>`。
|
||
- `Req-Atyou`：当前固定为 `true`。
|
||
|
||
响应 envelope：
|
||
|
||
```text
|
||
{
|
||
"status": bool,
|
||
"errorCode": int?,
|
||
"errorCodeName": string?,
|
||
"errorMsg": string?,
|
||
"body": any,
|
||
"time": number?
|
||
}
|
||
```
|
||
|
||
响应处理规则：
|
||
|
||
- `status == true` 才视为业务成功。
|
||
- `body` 由调用方传入的 `fromJson` 解析为领域响应模型。
|
||
- `status == false` 会通过 DioException 进入错误流程。
|
||
- 业务错误码集中参考 `lib/chatvibe_data/models/enum/at_erro_code.dart`。
|
||
- 不能在 UI 层直接解析后端 envelope；应在网络层、仓库层或 manager/provider 中处理。
|
||
|
||
特别注意：
|
||
|
||
- 当前仓库实现中，许多实际请求 path 是加密或映射后的字符串，真实业务接口名通常写在方法注释里，例如 `///auth/account/login`。
|
||
- 后续记录接口时，必须同时记录“业务接口名”和“当前实际请求 path”。
|
||
- 如果需要新增接口，不要猜测加密 path 或随意复用旧 path，必须先确认后端契约和当前前端映射方式。
|
||
|
||
---
|
||
|
||
## 7. 前端对接落地流程
|
||
|
||
每次对接新接口时，按以下步骤执行：
|
||
|
||
1. 确认当前线程负责的业务板块，不能越界顺手处理其它模块。
|
||
2. 只读查看后端接口文档、实际 handler/controller、契约和相关业务说明。
|
||
3. 在前端记录接口事实：业务接口名、当前实际请求 path、method、auth、request、response、错误码、后端证据文件。
|
||
4. 按当前项目分层落地：
|
||
- `lib/chatvibe_data/sources/remote/net/`：只维护通用网络能力、拦截器和响应 envelope。
|
||
- `lib/chatvibe_domain/models/req/`：新增或调整请求模型。
|
||
- `lib/chatvibe_domain/models/res/`：新增或调整响应模型。
|
||
- `lib/chatvibe_domain/repositories/`：声明业务仓库接口方法。
|
||
- `lib/chatvibe_data/sources/repositories/`：实现仓库接口并调用 `http.get/post/put/delete`。
|
||
- `lib/chatvibe_managers/` 或 `lib/chatvibe_features/<feature>/`：编排页面流程、加载态、错误态和状态更新。
|
||
- `lib/chatvibe_ui/`：只做通用 UI 组件，不放接口解析逻辑。
|
||
5. 接口错误、空数据、鉴权失败、字段缺失必须展示真实状态或走既有错误流程，禁止本地假数据兜底。
|
||
6. 如发现后端需要调整，写入“待后端确认事项”，明确“建议后端处理”，前端不改后端。
|
||
|
||
---
|
||
|
||
## 8. 本地假数据与兜底红线
|
||
|
||
对接真实接口时禁止：
|
||
|
||
- 接口报错后返回本地固定列表、固定对象或 mock JSON，让页面看起来正常。
|
||
- 字段缺失时在仓库层硬编码业务假值来绕过问题。
|
||
- 后端未返回权限、余额、身份、房间状态等关键字段时，前端自行推断并继续提交后续业务请求。
|
||
- 将调试用 mock、临时测试数据、接口样例数据留在正式逻辑中。
|
||
- 为了避免页面空态，把接口失败当作空列表成功。
|
||
|
||
允许：
|
||
|
||
- UI 展示空态、错误态、重试按钮、toast 或既有错误弹窗。
|
||
- 在开发调试环境中使用明确隔离的 mock，但不得进入正式接口对接逻辑。
|
||
- 对非关键展示字段使用产品确认过的展示默认值，例如空昵称展示 `--`；这不等同于业务数据兜底。
|
||
|
||
---
|
||
|
||
## 9. 接口事实记录模板
|
||
|
||
后续每个正式接入的接口，建议按以下格式记录在对应业务文档或本文件的接口记录区：
|
||
|
||
```text
|
||
### 接口名称
|
||
|
||
- 业务板块：
|
||
- 后端来源：
|
||
- 接口文档 / OpenAPI：
|
||
- Handler / Controller：
|
||
- Proto / RPC / Service：
|
||
- 业务接口名：
|
||
- 当前实际请求 path：
|
||
- Method：
|
||
- Auth：
|
||
- Request：
|
||
- Response body：
|
||
- 业务错误码：
|
||
- 前端落地位置：
|
||
- repository interface：
|
||
- repository impl：
|
||
- request model：
|
||
- response model：
|
||
- manager / provider / feature logic：
|
||
- page / widget：
|
||
- 是否存在本地假数据兜底：否
|
||
- 待后端确认：
|
||
- 当前状态：未接入 / 接入中 / 已接入 / 等后端确认
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 后端问题建议流转
|
||
|
||
如果前端对接时发现以下情况，不修改后端，只记录建议：
|
||
|
||
- 接口文档与实际 handler/controller 实现不一致。
|
||
- 字段缺失、字段含义不清、枚举值不完整。
|
||
- 错误码无法支撑前端区分提示。
|
||
- 接口返回结构不适合前端稳定渲染。
|
||
- 鉴权、幂等、分页、排序、时间单位、空态规则不明确。
|
||
- 后端当前只支持 mock 或占位实现。
|
||
- 前端需要新增接口、合并接口或调整响应字段。
|
||
- 当前前端需要真实接口，但后端尚未提供可用契约。
|
||
|
||
建议记录格式：
|
||
|
||
```text
|
||
- 【待后端确认｜业务板块｜YYYY-MM-DD HH:mm CST】
|
||
问题：
|
||
证据：
|
||
前端影响：
|
||
建议后端处理：
|
||
```
|
||
|
||
所有建议由用户协调后端团队处理；前端线程只负责说明影响、提供证据和调整前端对接方案。
|
||
|
||
---
|
||
|
||
## 11. 验证要求
|
||
|
||
接口对接完成后，至少给出以下验证：
|
||
|
||
- 静态检查：按改动范围运行 `flutter analyze` 或说明无法运行的原因。
|
||
- 模型解析：确认成功响应、空 body、字段缺失、错误响应不会导致非预期崩溃。
|
||
- 业务路径：验证页面正常加载、刷新、分页、提交、失败提示等主路径。
|
||
- 鉴权路径：验证未登录、token 失效或权限不足时走既有登录/错误流程。
|
||
- 回归范围：说明本次改动是否影响同仓库其它方法、共享模型、网络拦截器或全局错误处理。
|
||
|
||
如果是 bug 修复线程，还必须先说明 Root Cause，得到用户确认后再改代码，并坚持最小改动。
|
||
|
||
---
|
||
|
||
## 12. 当前可优先参考的前端文件
|
||
|
||
对接接口时，前端优先查看：
|
||
|
||
- `lib/chatvibe_data/sources/remote/net/network_client.dart`
|
||
- `lib/chatvibe_data/sources/remote/net/api.dart`
|
||
- `lib/chatvibe_data/sources/remote/net/at_logger.dart`
|
||
- `lib/chatvibe_data/models/enum/at_erro_code.dart`
|
||
- `lib/chatvibe_core/constants/at_global_config.dart`
|
||
- `lib/chatvibe_core/config/app_config.dart`
|
||
- `lib/chatvibe_core/config/configs/variant1_config.dart`
|
||
- `lib/chatvibe_domain/repositories/`
|
||
- `lib/chatvibe_data/sources/repositories/`
|
||
- `lib/chatvibe_domain/models/req/`
|
||
- `lib/chatvibe_domain/models/res/`
|
||
|
||
后端优先查看：
|
||
|
||
- `/Users/pinpaibu/server_code/likei-services/README.md`
|
||
- `/Users/pinpaibu/server_code/likei-services/rc-gateway/`
|
||
- `/Users/pinpaibu/server_code/likei-services/rc-auth/`
|
||
- `/Users/pinpaibu/server_code/likei-services/rc-service/`
|
||
- `/Users/pinpaibu/server_code/likei-services/rc-common-business/`
|
||
- `/Users/pinpaibu/server_code/likei-services/rc-service/rc-inner-api/`
|