Sample
基于 BSM-SDK Core 的 OPS 微服务样板项目，演示 Gin HTTP 服务、配置管理、数据库（GORM）、Redis 缓存、JWT 鉴权与标准分层架构，可作为新服务的起始模板。
功能概览
| 模块 | 说明 |
|---|---|
| 健康检查 | HEAD / 与 GET /Sample/v1/ping/hello |
| 示例 CRUD | Sample/v1/sample/demo 完整增删改查（JWT 鉴权） |
| 数据模型 | sample_demo 表，启动时自动迁移 |
| CLI | migrate 数据库迁移、version 版本查看 |
项目结构
sample/
├── cmd/
│ ├── main/ # HTTP 服务入口
│ └── cli/ # 命令行工具
├── internal/
│ ├── config/ # 配置加载与校验
│ ├── impl/ # 基础设施实例（DB、Redis、缓存、日志）
│ ├── logic/ # 业务逻辑层
│ │ ├── ping/ # 健康检查
│ │ └── demo/ # 示例 CRUD
│ ├── models/ # 数据模型与数据库操作
│ └── routers/ # 路由注册
├── etc/ # 配置文件（按环境区分）
├── scripts/ # 构建与工具脚本
├── test/ # HTTP 接口测试文件
└── Makefile
环境要求
- Go 1.26+
- PostgreSQL（或修改配置使用 MySQL）
- Redis
- 可访问
git.apinb.com私有仓库
快速开始
1. 配置 Go 私有仓库
go env -w GOPRIVATE=git.apinb.com/*
go env -w GONOPROXY=git.apinb.com/*
go env -w GOINSECURE=git.apinb.com/*
go env -w GONOSUMDB=git.apinb.com/*
2. 准备配置文件
配置文件命名规则：{服务键}_{运行模式}.yaml，本项目服务键为 Sample，开发模式对应 etc/sample_dev.yaml。
cp etc/sample_dev.yaml.example etc/sample_dev.yaml
# 编辑 etc/sample_dev.yaml，填入数据库与 Redis 连接信息
3. 设置环境变量
# Linux / macOS
export BSM_RuntimeMode=dev
export BSM_Prefix=$(pwd)/etc
export BSM_JwtSecretKey=your-secret-key
# Windows PowerShell
$env:BSM_RuntimeMode="dev"
$env:BSM_Prefix="$(pwd)/etc"
$env:BSM_JwtSecretKey="your-secret-key"
| 变量 | 说明 | 默认值 |
|---|---|---|
BSM_RuntimeMode |
运行模式：dev / test / prod |
dev |
BSM_Prefix |
配置文件目录 | 开发模式为当前路径 |
BSM_JwtSecretKey |
JWT 签名密钥 | SDK 内置默认值 |
BSM_Workspace |
工作空间标识 | default |
4. 安装依赖并启动
go mod tidy
make build # 或 go run ./cmd/main/main.go
make run
服务默认监听 12426 端口，启动成功后访问：
curl http://127.0.0.1:12426/Sample/v1/ping/hello
API 接口
统一响应格式
{
"code": 0,
"message": "",
"details": {},
"timeseq": 1710000000000
}
匿名接口
| 方法 | 路径 | 说明 |
|---|---|---|
HEAD |
/ |
健康检查 |
GET |
/Sample/v1/ping/hello |
Ping 测试 |
鉴权接口（JWT）
路由组：/Sample/v1/sample，请求头需携带 Authorization: Bearer <token>。
| 方法 | 路径 | 说明 |
|---|---|---|
POST |
/Sample/v1/demo |
创建示例数据 |
GET |
/Sample/v1/demo |
分页列表（page、size） |
GET |
/Sample/v1/demo/:identity |
按 identity 查询 |
PUT |
/Sample/v1/demo/:identity |
更新 |
DELETE |
/Sample/v1/demo/:identity |
删除 |
创建请求示例：
{
"name": "Alice",
"age": 25
}
CLI 工具
# 查看版本
go run ./cmd/cli/main.go version
# 执行数据库自动迁移（模型定义见 internal/models）
go run ./cmd/cli/main.go migrate
也可使用 Makefile：
make migrate
make cli ARGS="version"
开发与测试
make lint # go vet + go fmt
make tidy # go mod tidy
接口测试文件位于 test/ 目录，可使用 VS Code REST Client 或 IntelliJ HTTP Client 直接运行。
生产部署
构建
./scripts/build.sh
# 产物：build/sample、build/sample-cli
systemd
cp etc/sample.service /etc/systemd/system/
cp etc/sample.env.example /data/app/etc/sample.env
# 编辑环境变量后
systemctl enable sample
systemctl start sample