更新依赖和调整目录结构，未修改模块
This commit is contained in:
@@ -3,6 +3,7 @@
|
||||
| 文档 | 内容 |
|
||||
| --- | --- |
|
||||
| [系统架构](architecture.md) | 模块边界、聚合入口、请求分流和依赖注入 |
|
||||
| [电商聚合开发上下文](../pkgs/ecmall/AGENT.md) | pkgs/ecmall 的注册表、配置、跨模块耦合、业务链路、缺口清单和开发指引 |
|
||||
| [开发与运维](operations.md) | 配置、启动、验证、构建、发布和排障 |
|
||||
| [审计报告](audit-2026-08-10.md) | 已修复问题、剩余风险和后续优先级 |
|
||||
| [API 接入总览](api/00-overview.md) | gRPC、动态 HTTP RPC、grpc-gateway、鉴权和 JSON 规则 |
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
# API 接入总览
|
||||
|
||||
本文档面向 Web、移动端和第三方客户端开发者。默认示例基于 `all` 聚合服务：gRPC 监听 `12000`，HTTP 监听 `12001`，实际地址以 `all/etc/<workspace>_<runtime>.yaml` 为准。
|
||||
本文档面向 Web、移动端和第三方客户端开发者。默认示例基于 `pkgs/all` 聚合服务：gRPC 监听 `12000`，HTTP 监听 `12001`，实际地址以 `pkgs/all/etc/<workspace>_<runtime>.yaml` 为准。
|
||||
|
||||
电商客户端可以改用 `pkgs/ecmall` 聚合服务：它注册除 cloud 外的 initial、passport、sender、ads、cms、feedback、fts、logs、mgt、address、mall、market、order、wallet，gRPC 监听 `12300`，HTTP 监听 `12301`，配置位于 `pkgs/ecmall/etc/`。本目录中除 cloud 以外的章节对该入口同样适用，其中 ads、cms、feedback 走 gRPC/gateway，fts、logs、mgt 为原生 REST。
|
||||
|
||||
## 协议入口
|
||||
|
||||
@@ -70,7 +72,7 @@ Content-Type: application/json
|
||||
Authorization: <JWT>
|
||||
```
|
||||
|
||||
请求头直接传递 JWT，不添加 `Bearer` 前缀。`all` 使用 `Authorization.Key` 验证 HS256 签名，并根据 token 的 `exp` 与 `Authorization.Expire` 校验有效期；是否匿名由 `Authorization.Anonymous` 配置决定。
|
||||
请求头直接传递 JWT，不添加 `Bearer` 前缀。`pkgs/all` 使用 `Authorization.Key` 验证 HS256 签名，并根据 token 的 `exp` 与 `Authorization.Expire` 校验有效期；是否匿名由 `Authorization.Anonymous` 配置决定。
|
||||
|
||||
## 当前限制与风险
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
## 模块边界
|
||||
|
||||
仓库包含 20 个 Go module：module 下 19 个业务模块可独立运行，all 聚合其中 15 个 base、ec、finance 服务；social 三个模块暂未聚合。
|
||||
仓库包含 21 个 Go module：`module/` 下 18 个业务模块可独立运行，`pkgs/all` 聚合其中 15 个 base、ec、finance 服务，`pkgs/ecmall` 聚合其中 14 个 base、ec、finance 服务（不含 cloud）；social 三个模块暂未聚合，`scripts/api-docgen` 是文档生成工具 module，不属于业务服务。
|
||||
|
||||
典型模块目录职责：
|
||||
|
||||
@@ -13,13 +13,13 @@
|
||||
| internal/impl | DB、Redis、etcd、内存缓存 |
|
||||
| internal/logic | 业务逻辑 |
|
||||
| internal/server | 服务构造与注册 |
|
||||
| service | 对 all 公开的 Expose API |
|
||||
| service | 对聚合宿主（`pkgs/all`、`pkgs/ecmall`）公开的 Expose API |
|
||||
| pb | protobuf 生成代码 |
|
||||
| etc | 配置样例 |
|
||||
|
||||
独立入口初始化自己的基础设施。聚合调用 Expose 时不重复初始化，而是注入 all 创建的共享对象。
|
||||
独立入口初始化自己的基础设施。聚合调用 Expose 时不重复初始化，而是注入 `pkgs/all` 创建的共享对象。
|
||||
|
||||
## all 启动流程
|
||||
## pkgs/all 启动流程
|
||||
|
||||
1. 校验 --workspace 并读取 etc/<workspace>_<runtime>.yaml。
|
||||
2. 初始化共享 DB、Redis、etcd 和内存缓存。
|
||||
@@ -29,6 +29,20 @@
|
||||
|
||||
HTTP 请求先进入 grpc-gateway；gateway 返回 404 时回退到 Gin。Gin 提供 `/rpc/{package}/{service}/{method}` 动态 JSON-to-protobuf unary 调用，以及 `/rest/{module}/...` 原生 REST 路由。动态调用通过本机 gRPC 端口进入完整 gRPC 处理链。
|
||||
|
||||
## pkgs/ecmall 启动流程
|
||||
|
||||
`pkgs/ecmall` 与 `pkgs/all` 共享同一套 server、鉴权、动态 RPC 与配置装配实现，启动流程完全一致，差别只在注册表、端口和专项配置：
|
||||
|
||||
| 项目 | pkgs/all | pkgs/ecmall |
|
||||
| --- | --- | --- |
|
||||
| module 路径 | bsm/full/pkgs/all | bsm/full/pkgs/ecmall |
|
||||
| 监听端口 | gRPC 12000 / HTTP 12001 | gRPC 12300 / HTTP 12301 |
|
||||
| 注册服务 | 15 个（10 base + 4 ec + wallet） | 14 个（9 base + 4 ec + wallet，不含 cloud） |
|
||||
| 专项配置 | Fts、Mgt、Passport、Sender、Wallet | Fts、Mgt、Passport、Sender、Wallet |
|
||||
| 本地 replace | 15 个业务模块 | 14 个业务模块 |
|
||||
|
||||
`ecmall` 的注册表包含除 cloud 外的全部 base、ec、finance 服务，未注册的 cloud 既不会暴露 gRPC/gateway 路由，也不会解析其专项配置。两个入口使用同一份 `module/` 代码，可同时运行。
|
||||
|
||||
## 依赖注入
|
||||
|
||||
ExposeOptions.Dependencies 可接收 RedisClient、etcd Client、gorm DB 和 Cache。参数非 nil 时覆盖模块 internal/impl 对象。address、market、order、mgt 的业务数据库访问已统一使用 internal/impl.DBService。
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
## 范围
|
||||
|
||||
覆盖根 workspace、all、19 个业务模块、配置样例和维护脚本。执行结构盘点、敏感信息扫描、TODO/异常退出扫描和全部 module 测试。
|
||||
覆盖根 workspace、`pkgs/all`、19 个业务模块、配置样例和维护脚本。执行结构盘点、敏感信息扫描、TODO/异常退出扫描和全部 module 测试。
|
||||
|
||||
## 已修复
|
||||
|
||||
@@ -28,7 +28,7 @@ market 和 mall 的账号创建、登录、改密及初始化密码已从 MD5
|
||||
|
||||
### P1：reflection 与明文 h2c
|
||||
|
||||
all 默认启用 gRPC reflection，自身不终止 TLS。生产环境应在可信网络运行，由网关终止 TLS，并将 reflection 改为配置控制。
|
||||
`pkgs/all` 默认启用 gRPC reflection，自身不终止 TLS。生产环境应在可信网络运行，由网关终止 TLS，并将 reflection 改为配置控制。
|
||||
|
||||
### P1：未实现接口
|
||||
|
||||
@@ -36,7 +36,7 @@ social、wallet、mall、cms 等仍有模板 TODO。编译成功不代表功能
|
||||
|
||||
### P2：测试覆盖不足
|
||||
|
||||
多数 package 没有测试。应优先覆盖认证、权限、支付、订单状态机、迁移和 all 请求分流。
|
||||
多数 package 没有测试。应优先覆盖认证、权限、支付、订单状态机、迁移和 `pkgs/all` 请求分流。
|
||||
|
||||
### P2：迁移与启动耦合
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
|
||||
<BSM_Prefix>/etc/<serviceKey>_<BSM_RuntimeMode>.yaml
|
||||
|
||||
all 的 serviceKey 来自 --workspace，默认 default。BSM_RuntimeMode 默认 dev，BSM_SERVICES 可覆盖聚合服务列表。
|
||||
`pkgs/all` 与 `pkgs/ecmall` 的 serviceKey 来自 --workspace，默认 default。BSM_RuntimeMode 默认 dev，BSM_SERVICES 可覆盖聚合服务列表；`pkgs/ecmall` 的配置文件位于 `pkgs/ecmall/etc/`，默认监听 gRPC 12300 / HTTP 12301。
|
||||
|
||||
## 验证
|
||||
|
||||
@@ -22,10 +22,13 @@ Linux/macOS：
|
||||
|
||||
## 构建
|
||||
|
||||
scripts/build-all-linux.sh 构建 module 下独立服务到 .builds。all 可单独构建：
|
||||
scripts/build-all-linux.sh 构建 module 下独立服务到 .builds。`pkgs/all` 和 `pkgs/ecmall` 可分别单独构建：
|
||||
|
||||
cd all
|
||||
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -o ../.builds/all ./cmd/main
|
||||
cd pkgs/all
|
||||
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -o ../../.builds/all ./cmd/main
|
||||
|
||||
cd pkgs/ecmall
|
||||
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -o ../../.builds/ecmall ./cmd/main
|
||||
|
||||
## 发布检查
|
||||
|
||||
|
||||
Reference in New Issue
Block a user