216 lines
4.4 KiB
Markdown
216 lines
4.4 KiB
Markdown
# ChatAppGateway 第一版 prompt
|
||
|
||
你是一名资深 Golang 后端架构师，请为一个海外社交 App 实现一个主业务聚合服务 `ChatAppGateway`。
|
||
|
||
## 服务定位
|
||
|
||
- `ChatAppGateway` 不是纯反向代理网关，而是 BFF / 聚合编排服务。
|
||
- 对客户端暴露 HTTP JSON API。
|
||
- 对内通过 `Common` 里的 proto 调用：
|
||
- `ChatAppUserService.Register`
|
||
- `ChatAppPayService.Pay`
|
||
- 自身不实现用户域认证规则，也不实现支付域核心规则，只做参数校验、字段归一化、协议适配、统一错误响应、日志与 trace。
|
||
|
||
## 目标能力
|
||
|
||
第一版只实现三条 HTTP 接口：
|
||
|
||
1. `GET /health`
|
||
2. `GET /ready`
|
||
3. `POST /api/v1/users/register`
|
||
4. `POST /api/v1/pay`
|
||
|
||
## 配置要求
|
||
|
||
配置文件放在 `config/xxx.yaml`，默认读取 `config/local.yaml`。
|
||
|
||
YAML 结构固定如下：
|
||
|
||
```yaml
|
||
app:
|
||
name: chatappgateway
|
||
env: local
|
||
http_addr: ":8080"
|
||
shutdown_timeout: 10s
|
||
|
||
grpc:
|
||
user:
|
||
target: "127.0.0.1:9001"
|
||
timeout: 3s
|
||
pay:
|
||
target: "127.0.0.1:9002"
|
||
timeout: 3s
|
||
```
|
||
|
||
必须支持：
|
||
|
||
- `-config config/local.yaml` 命令行参数
|
||
- `gopkg.in/yaml.v3`
|
||
- 默认值补齐
|
||
- 配置校验
|
||
|
||
## 登录接口要求
|
||
|
||
`POST /api/v1/users/register`
|
||
|
||
请求 DTO 至少包含：
|
||
|
||
- `login_type`
|
||
- `account`
|
||
- `password`
|
||
- `country_code`
|
||
- `verify_code`
|
||
- `provider`
|
||
- `provider_token`
|
||
- `device_id`
|
||
- `platform`
|
||
- `app_version`
|
||
|
||
支持三种登录模式：
|
||
|
||
1. `password`
|
||
- 必填：`account`、`password`
|
||
2. `sms_code`
|
||
- 必填：`country_code`、`account`、`verify_code`
|
||
3. `oauth`
|
||
- 必填：`provider`、`provider_token`
|
||
|
||
网关职责：
|
||
|
||
- 做基础参数校验和字段归一化
|
||
- 将请求映射到 `ChatAppUserService.Register`
|
||
- 接收用户服务返回后再统一包装给客户端
|
||
|
||
`ChatAppUserService.Register` 返回至少包含：
|
||
|
||
- `user_id`
|
||
- `access_token`
|
||
- `is_new_user`
|
||
- `profile`
|
||
|
||
其中 `profile` 至少包含：
|
||
|
||
- `user_id`
|
||
- `nickname`
|
||
- `avatar_url`
|
||
|
||
## 支付查询接口要求
|
||
|
||
`POST /api/v1/pay`
|
||
|
||
网关职责：
|
||
|
||
- 校验 `order_no` 非空
|
||
- 调用 `ChatAppPayService.Pay`
|
||
- 把支付服务返回的订单结果转成统一 HTTP JSON 响应
|
||
|
||
返回字段至少包含：
|
||
|
||
- `payment_id`
|
||
- `order_no`
|
||
- `user_id`
|
||
- `status`
|
||
- `amount`
|
||
- `currency`
|
||
- `pay_method`
|
||
- `subject`
|
||
- `created_at`
|
||
|
||
## 健康检查要求
|
||
|
||
`GET /health`
|
||
|
||
- 只做网关自身存活检查
|
||
- 固定返回 200
|
||
- 返回：
|
||
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"service": "chatappgateway"
|
||
}
|
||
```
|
||
|
||
`GET /ready`
|
||
|
||
- 用于 K8s / LB readiness probe
|
||
- 不是只判断进程活着
|
||
- 至少要判断：
|
||
- 配置已经成功加载
|
||
- 关键依赖已经连通
|
||
- 服务已经具备接流量能力
|
||
- 对 `ChatAppGateway` 第一版来说，`/ready` 至少检查：
|
||
- `ChatAppUser` 的 gRPC 连接可用
|
||
- `ChatAppPay` 的 gRPC 连接可用
|
||
- 返回 200 时表示可以接流量，失败时返回 503
|
||
|
||
## 错误码和状态码要求
|
||
|
||
- 参数错误：`400`
|
||
- 注册失败或凭证错误：`401`
|
||
- 订单不存在：`404`
|
||
- 下游 gRPC 超时：`504`
|
||
- 下游 gRPC 不可用或内部异常：`502`
|
||
|
||
要求统一 JSON 错误结构，例如：
|
||
|
||
```json
|
||
{
|
||
"code": "bad_request",
|
||
"message": "login_type is required",
|
||
"request_id": "..."
|
||
}
|
||
```
|
||
|
||
## 目录结构要求
|
||
|
||
项目目录至少包含：
|
||
|
||
- `cmd/gateway/main.go`
|
||
- `internal/config`
|
||
- `internal/app`
|
||
- `internal/transport/http`
|
||
- `internal/integration/usergrpc`
|
||
- `internal/integration/paygrpc`
|
||
- `internal/service/auth`
|
||
- `internal/service/pay`
|
||
- `api/proto`
|
||
- `config/local.yaml`
|
||
|
||
## 技术要求
|
||
|
||
- 使用 idiomatic Go
|
||
- 使用 `http.ServeMux`
|
||
- 使用 `slog` 结构化日志
|
||
- 支持优雅关闭
|
||
- 收到 `SIGTERM` 后先摘除 `/ready`，再停止接新请求，等待旧请求处理完成后退出
|
||
- gRPC 连接使用 `insecure.NewCredentials()` 即可
|
||
- 所有关键代码写中文注释
|
||
- 不要写成教学 demo，要保持生产风格
|
||
|
||
## 测试要求
|
||
|
||
至少覆盖以下场景：
|
||
|
||
- 配置加载成功
|
||
- 配置非法时失败
|
||
- `/health` 返回正确 JSON
|
||
- `/ready` 在依赖可用时返回 200，在依赖不可用时返回 503
|
||
- 三种 `login_type` 的参数校验
|
||
- 登录请求正确映射到 `ChatAppUser.Login`
|
||
- 订单查询正确映射到 `ChatAppPay.QueryOrder`
|
||
- user/pay gRPC 超时、不可达、业务错误时的 HTTP 状态码映射
|
||
|
||
## 输出顺序要求
|
||
|
||
请按以下顺序输出实现内容：
|
||
|
||
1. 项目目录结构
|
||
2. proto 定义
|
||
3. 配置结构与示例
|
||
4. HTTP API 设计
|
||
5. gRPC client 封装
|
||
6. Go 代码实现
|
||
7. 测试代码
|
||
8. 本地运行说明
|