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