设计

2026-06-21 17:50:24 +08:00
parent 360317fba8
commit 17063cbad0
291 changed files with 35717 additions and 1 deletions
--- a/templates/server_sample/README.md
+++ b/templates/server_sample/README.md
@@ -0,0 +1,183 @@
+# Sample
+
+基于 [BSM-SDK Core](https://git.apinb.com/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 私有仓库
+
+```bash
+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`。
+
+```bash
+cp etc/sample_dev.yaml.example etc/sample_dev.yaml
+# 编辑 etc/sample_dev.yaml，填入数据库与 Redis 连接信息
+```
+
+### 3. 设置环境变量
+
+```bash
+# 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. 安装依赖并启动
+
+```bash
+go mod tidy
+make build          # 或 go run ./cmd/main/main.go
+make run
+```
+
+服务默认监听 `12426` 端口，启动成功后访问：
+
+```bash
+curl http://127.0.0.1:12426/Sample/v1/ping/hello
+```
+
+## API 接口
+
+### 统一响应格式
+
+```json
+{
+  "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` | 删除 |
+
+**创建请求示例：**
+
+```json
+{
+  "name": "Alice",
+  "age": 25
+}
+```
+
+## CLI 工具
+
+```bash
+# 查看版本
+go run ./cmd/cli/main.go version
+
+# 执行数据库自动迁移（模型定义见 internal/models）
+go run ./cmd/cli/main.go migrate
+```
+
+也可使用 Makefile：
+
+```bash
+make migrate
+make cli ARGS="version"
+```
+
+## 开发与测试
+
+```bash
+make lint           # go vet + go fmt
+make tidy           # go mod tidy
+```
+
+接口测试文件位于 `test/` 目录，可使用 VS Code REST Client 或 IntelliJ HTTP Client 直接运行。
+
+## 生产部署
+
+### 构建
+
+```bash
+./scripts/build.sh
+# 产物：build/sample、build/sample-cli
+```
+
+### systemd
+
+```bash
+cp etc/sample.service /etc/systemd/system/
+cp etc/sample.env.example /data/app/etc/sample.env
+# 编辑环境变量后
+systemctl enable sample
+systemctl start sample
+```
+
+