136 lines
4.3 KiB
Markdown
136 lines
4.3 KiB
Markdown
# BSM Infra Full
|
||
|
||
BSM 后端服务的 Go workspace，包含基础能力、电商、财务、社交服务，以及可选择组件运行的单体入口。所有模块统一使用 **Go 1.26.5**。
|
||
|
||
## 目录结构
|
||
|
||
| 目录 | 服务 |
|
||
| --- | --- |
|
||
| `module/base` | ads、cloud、cms、feedback、fts、initial、logs、mgt、passport、sender |
|
||
| `module/ec` | address、delivery、mall、market、order |
|
||
| `module/finance` | wallet |
|
||
| `module/social` | feed、group、relation |
|
||
| `protobuf` | 跨服务共享的 protobuf 定义，目前包含 `blocks.proto` |
|
||
| `cmd` | 聚合上述服务的单体启动器 |
|
||
| `go.work` | 21 个 Go 模块的 workspace 定义 |
|
||
|
||
各服务的接口、配置和部署细节见对应 `module/**/README.md`。
|
||
|
||
## 环境要求
|
||
|
||
- Go 1.26.5
|
||
- Git
|
||
- 按所运行服务准备 PostgreSQL、Redis、etcd、MQ 或对象存储等外部依赖
|
||
- 重新生成 protobuf 时可使用仓库内 `.tools/` 的工具，或在 `PATH` 中安装 `protoc`、`protoc-gen-go`、`protoc-gen-go-grpc` 和 `protoc-gen-grpc-gateway`
|
||
|
||
确认工具链：
|
||
|
||
```bash
|
||
go version
|
||
go work sync
|
||
```
|
||
|
||
统一重新生成 protobuf：
|
||
|
||
```bash
|
||
bash scripts/generate-protobuf.sh
|
||
```
|
||
|
||
脚本以根目录 `protobuf/blocks.proto` 为共享定义，并为各服务生成 protobuf、gRPC 和 grpc-gateway 代码。生成后的兼容别名继续保留旧模块中的公共类型名。
|
||
|
||
更新所有 workspace 模块的依赖：
|
||
|
||
```bash
|
||
bash scripts/update-all.sh
|
||
```
|
||
|
||
脚本会为每个模块执行 `go get -u ./...` 和 `go mod tidy`，最后运行 `go work sync`；它不会自动提交或推送 Git 变更。
|
||
|
||
编译全部 19 个独立服务：
|
||
|
||
```bash
|
||
bash scripts/build-all-linux.sh
|
||
```
|
||
|
||
脚本固定交叉编译 Linux x86-64（`GOOS=linux`、`GOARCH=amd64`、`CGO_ENABLED=0`），产物写入 `builds/<领域>-<模块>`。`builds/` 已加入 `.gitignore`，聚合入口 `cmd` 不包含在批量构建中。
|
||
|
||
## 配置
|
||
|
||
每个服务的 `etc/` 目录包含 `*_dev.yaml`、`*_test.yaml` 和 `*_prod.yaml` 示例。提交到仓库的配置只能包含占位值；请在本地副本或部署系统的密钥管理中注入真实凭据，不要提交数据库密码、访问密钥、令牌或私钥。
|
||
|
||
本仓库审计时已移除过明文凭据。如果这些凭据曾在真实环境使用，应立即在数据库、SMTP、对象存储及相关服务侧轮换。
|
||
|
||
## 运行
|
||
|
||
运行单个服务时，进入其模块目录。例如：
|
||
|
||
```bash
|
||
cd module/base/passport
|
||
go run ./cmd/main
|
||
```
|
||
|
||
运行聚合入口：
|
||
|
||
```bash
|
||
cd cmd
|
||
go run ./main
|
||
```
|
||
|
||
默认启动全部可聚合组件。通过 `BSM_SERVICES` 选择服务，名称以逗号分隔：
|
||
|
||
```bash
|
||
# Linux/macOS
|
||
BSM_SERVICES=passport,order,wallet go run ./main
|
||
|
||
# PowerShell
|
||
$env:BSM_SERVICES = "passport,order,wallet"
|
||
go run ./main
|
||
```
|
||
|
||
可选组件为：`ads`、`cloud`、`cms`、`feedback`、`fts`、`initial`、`logs`、`mgt`、`passport`、`sender`、`address`、`delivery`、`mall`、`market`、`order`、`wallet`。社交服务目前作为独立模块运行，尚未接入聚合入口。
|
||
|
||
## 测试
|
||
|
||
根目录不是 Go module，因此不要在根目录执行 `go test ./...`。应逐 workspace 模块测试。
|
||
|
||
PowerShell：
|
||
|
||
```powershell
|
||
go list -m -f '{{.Dir}}' | ForEach-Object {
|
||
Push-Location $_
|
||
try { go test ./... } finally { Pop-Location }
|
||
}
|
||
```
|
||
|
||
Linux/macOS：
|
||
|
||
```bash
|
||
go list -m -f '{{.Dir}}' | while IFS= read -r module; do
|
||
(cd "$module" && go test ./...)
|
||
done
|
||
```
|
||
|
||
依赖运行中服务或真实基础设施的测试带有 `integration` build tag，默认测试不会访问外部系统。准备好测试环境和对应的 `BSM_*_TOKEN` 等变量后，在目标模块显式运行：
|
||
|
||
```bash
|
||
go test -tags=integration ./...
|
||
```
|
||
|
||
建议提交前执行：
|
||
|
||
```bash
|
||
gofmt -w .
|
||
go vet ./...
|
||
go test ./...
|
||
```
|
||
|
||
最后两条命令需在每个模块目录执行，可使用上面的 workspace 循环。
|
||
|
||
## 开发约定
|
||
|
||
- Go 版本声明、Docker 构建镜像和 CI 构建镜像统一为 `1.26.5`。
|
||
- 新模块必须加入 `go.work`，并确保本地 `replace` 使用当前 `module/...` 目录结构。
|
||
- protobuf 描述符必须包含服务命名空间，避免多个服务聚合到同一进程时发生全局文件名冲突。
|
||
- 外部依赖测试使用 `//go:build integration`，不得让默认测试依赖网络或已启动服务。
|
||
- 配置和测试数据中不得包含真实凭据或个人信息。
|