ops-v2/ops

Fork 0

Files

zxr 17063cbad0 设计

2026-06-21 17:50:24 +08:00

4.2 KiB

Raw Blame History

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

4.2 KiB Raw Blame History Unescape Escape