full/README.md

BSM Infra Full

BSM 后端服务的 Go workspace，包含基础能力、电商、财务、社交服务，以及可选择组件运行的单体入口。所有模块统一使用 Go 1.26.5。

目录结构

目录	服务
apps/base	ads、cloud、cms、feedback、fts、initial、logs、mgt、passport、sender
apps/ec	address、delivery、mall、market、order
apps/finance	wallet
apps/social	feed、group、relation
cmd	聚合上述服务的单体启动器
go.work	20 个 Go 模块的 workspace 定义

各服务的接口、配置和部署细节见对应 apps/**/README.md。

环境要求

• Go 1.26.5
• Git
• 按所运行服务准备 PostgreSQL、Redis、etcd、MQ 或对象存储等外部依赖
• 重新生成 protobuf 时，按服务目录中的 buf.yaml、buf.gen.yaml 和脚本安装相应生成器

确认工具链：

go version
go work sync

配置

每个服务的 etc/ 目录包含 *_dev.yaml、*_test.yaml 和 *_prod.yaml 示例。提交到仓库的配置只能包含占位值；请在本地副本或部署系统的密钥管理中注入真实凭据，不要提交数据库密码、访问密钥、令牌或私钥。

本仓库审计时已移除过明文凭据。如果这些凭据曾在真实环境使用，应立即在数据库、SMTP、对象存储及相关服务侧轮换。

运行

运行单个服务时，进入其模块目录。例如：

cd apps/base/passport
go run ./cmd/main

运行聚合入口：

cd cmd
go run ./main

默认启动全部可聚合组件。通过 BSM_SERVICES 选择服务，名称以逗号分隔：

# 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：

go list -m -f '{{.Dir}}' | ForEach-Object {
    Push-Location $_
    try { go test ./... } finally { Pop-Location }
}

Linux/macOS：

go list -m -f '{{.Dir}}' | while IFS= read -r module; do
  (cd "$module" && go test ./...)
done

依赖运行中服务或真实基础设施的测试带有 integration build tag，默认测试不会访问外部系统。准备好测试环境和对应的 BSM_*_TOKEN 等变量后，在目标模块显式运行：

go test -tags=integration ./...

建议提交前执行：

gofmt -w .
go vet ./...
go test ./...

最后两条命令需在每个模块目录执行，可使用上面的 workspace 循环。

开发约定

• Go 版本声明、Docker 构建镜像和 CI 构建镜像统一为 1.26.5。
• 新模块必须加入 go.work，并确保本地 replace 使用当前 apps/... 目录结构。
• protobuf 描述符必须包含服务命名空间，避免多个服务聚合到同一进程时发生全局文件名冲突。
• 外部依赖测试使用 //go:build integration，不得让默认测试依赖网络或已启动服务。
• 配置和测试数据中不得包含真实凭据或个人信息。