184 lines
4.2 KiB
Markdown
184 lines
4.2 KiB
Markdown
# 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
|
||
```
|
||
|
||
|