Initial commit
This commit is contained in:
290
README.md
Normal file
290
README.md
Normal file
@@ -0,0 +1,290 @@
|
||||
# 浙江贝凡溯源管理平台 - 后端服务 (Go 版本)
|
||||
|
||||
这是一个使用 Go 语言开发的溯源管理平台后端服务，提供序列号生成、查询、管理等功能。
|
||||
|
||||
## 技术栈
|
||||
|
||||
- **Web 框架**: Gin (高性能 HTTP 框架)
|
||||
- **ORM**: GORM (Go 对象关系映射)
|
||||
- **数据库**:
|
||||
- SQLite (默认，适用于开发和轻量级部署)
|
||||
- PostgreSQL (生产环境推荐)
|
||||
- **认证**: JWT (JSON Web Token) - golang-jwt/jwt/v5
|
||||
- **密码加密**: bcrypt (golang.org/x/crypto)
|
||||
- **二维码生成**: yeqown/go-qrcode/v2
|
||||
- **配置管理**:
|
||||
- Viper (环境变量和配置文件)
|
||||
- gotenv (.env 文件加载)
|
||||
- **日志**: Zap (高性能结构化日志)
|
||||
- **验证**: go-playground/validator
|
||||
- **测试**: Testify (测试框架)
|
||||
- **工具**: UUID (github.com/google/uuid)
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
backend-go/
|
||||
├── config/ # 配置管理
|
||||
│ └── config.go # 配置加载和解析（支持 .env 文件和环境变量）
|
||||
├── controllers/ # 控制器层，处理 HTTP 请求
|
||||
│ ├── auth_controller.go # 认证相关接口
|
||||
│ ├── companies_controller.go # 企业管理接口
|
||||
│ ├── helper.go # 控制器通用辅助函数
|
||||
│ └── serials_controller.go # 序列号管理接口
|
||||
├── database/ # 数据库连接和操作
|
||||
│ └── database.go # 数据库初始化、连接池配置
|
||||
├── logger/ # 日志管理
|
||||
│ └── logger.go # 结构化日志（使用 Zap）
|
||||
├── middleware/ # 中间件层
|
||||
│ └── auth.go # JWT 认证和权限检查
|
||||
├── models/ # 数据模型和 DTO
|
||||
│ └── models.go # User、Company、Serial 等模型定义
|
||||
├── routes/ # 路由配置
|
||||
│ └── routes.go # API 路由注册
|
||||
├── services/ # 业务逻辑层
|
||||
│ ├── auth_service.go # 认证业务逻辑
|
||||
│ ├── companies_service.go # 企业管理业务逻辑
|
||||
│ ├── serials_service.go # 序列号业务逻辑
|
||||
│ └── services_test.go # 服务层单元测试
|
||||
├── tests/ # 集成测试
|
||||
│ └── main_test.go # 端到端测试
|
||||
├── data/ # 数据目录 (SQLite 数据库存储)
|
||||
├── main.go # 应用程序入口
|
||||
├── go.mod # Go 模块依赖
|
||||
├── go.sum # Go 模块校验和
|
||||
├── Makefile # 构建和开发任务
|
||||
├── .env.example # 环境变量示例
|
||||
├── .env # 环境变量配置（需手动创建）
|
||||
├── .golangci.yml # 代码检查配置
|
||||
└── .gitignore # Git 忽略文件
|
||||
```
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 安装依赖
|
||||
|
||||
```bash
|
||||
cd backend-go
|
||||
go mod download
|
||||
|
||||
# 或使用 Makefile
|
||||
make deps
|
||||
```
|
||||
|
||||
### 2. 配置环境变量
|
||||
|
||||
复制 `.env.example` 文件为 `.env` 并根据需要修改：
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
**重要**: 生产环境请务必修改 `JWT_SECRET` 环境变量！
|
||||
|
||||
### 3. 使用 Makefile（推荐）
|
||||
|
||||
```bash
|
||||
# 启动开发服务器
|
||||
make run
|
||||
|
||||
# 编译项目
|
||||
make build
|
||||
|
||||
# 运行测试
|
||||
make test
|
||||
|
||||
# 生成测试覆盖率报告
|
||||
make test-coverage
|
||||
|
||||
# 代码质量检查
|
||||
make quality
|
||||
|
||||
# 清理构建文件
|
||||
make clean
|
||||
```
|
||||
|
||||
### 4. 手动启动
|
||||
|
||||
```bash
|
||||
go run main.go
|
||||
```
|
||||
|
||||
服务器将在 http://localhost:3000 上运行。
|
||||
|
||||
### 5. 环境变量配置
|
||||
|
||||
项目支持以下环境变量（按优先级排序）：
|
||||
|
||||
| 变量名 | 说明 | 默认值 |
|
||||
|--------|------|--------|
|
||||
| `PORT` | 服务器端口 | 3000 |
|
||||
| `ENVIRONMENT` | 运行环境 (development/production) | development |
|
||||
| `JWT_SECRET` | JWT 签名密钥 | your-secret-key-here-change-in-production |
|
||||
| `JWT_EXPIRE` | JWT 过期时间（秒） | 7200 |
|
||||
| `DATABASE_DRIVER` | 数据库驱动 (sqlite/postgres) | sqlite |
|
||||
| `DATABASE_PATH` | SQLite 数据库路径 | ./data/database.sqlite |
|
||||
| `POSTGRES_HOST` | PostgreSQL 主机 | localhost |
|
||||
| `POSTGRES_PORT` | PostgreSQL 端口 | 5432 |
|
||||
| `POSTGRES_USER` | PostgreSQL 用户名 | trace |
|
||||
| `POSTGRES_PASSWORD` | PostgreSQL 密码 | trace123 |
|
||||
| `POSTGRES_DB` | PostgreSQL 数据库名 | trace |
|
||||
| `POSTGRES_SSLMODE` | PostgreSQL SSL 模式 | disable |
|
||||
|
||||
**注意**: 环境变量也可以通过 `.env` 文件设置。
|
||||
|
||||
### 6. 测试 API
|
||||
|
||||
**健康检查**:
|
||||
|
||||
```bash
|
||||
curl -X GET http://localhost:3000/api/health
|
||||
```
|
||||
|
||||
**用户登录**:
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username":"admin","password":"password123"}'
|
||||
```
|
||||
|
||||
## API 文档
|
||||
|
||||
### 认证路由
|
||||
|
||||
| 方法 | 路径 | 描述 | 需要认证 |
|
||||
| ---- | --------------------------- | ----------------------- | -------- |
|
||||
| POST | `/api/auth/login` | 用户登录，返回 JWT 令牌 | 否 |
|
||||
| GET | `/api/auth/profile` | 获取当前用户信息 | 是 |
|
||||
| PUT | `/api/auth/profile` | 更新用户信息 | 是 |
|
||||
| POST | `/api/auth/change-password` | 修改密码 | 是 |
|
||||
|
||||
### 序列号管理
|
||||
|
||||
| 方法 | 路径 | 描述 | 需要认证 | 角色 |
|
||||
| ---- | ----------------------------------- | ---------------- | -------- | ------ |
|
||||
| POST | `/api/serials/generate` | 生成序列号 | 是 | 管理员 |
|
||||
| POST | `/api/serials/generate-with-prefix` | 带前缀生成序列号 | 是 | 管理员 |
|
||||
| POST | `/api/serials/:serialNumber/qrcode` | 生成序列号二维码 | 是 | 任何 |
|
||||
| GET | `/api/serials/:serialNumber/query` | 查询序列号信息 | 否 | 任何 |
|
||||
| GET | `/api/serials` | 获取序列号列表 | 是 | 任何 |
|
||||
| PUT | `/api/serials/:serialNumber` | 更新序列号信息 | 是 | 管理员 |
|
||||
| POST | `/api/serials/:serialNumber/revoke` | 吊销序列号 | 是 | 管理员 |
|
||||
|
||||
### 企业管理
|
||||
|
||||
| 方法 | 路径 | 描述 | 需要认证 | 角色 |
|
||||
| ------ | ----------------------------- | ------------ | -------- | ------ |
|
||||
| GET | `/api/companies` | 获取企业列表 | 是 | 任何 |
|
||||
| POST | `/api/companies` | 创建新企业 | 是 | 管理员 |
|
||||
| PUT | `/api/companies/:companyName` | 更新企业信息 | 是 | 管理员 |
|
||||
| DELETE | `/api/companies/:companyName` | 删除企业 | 是 | 管理员 |
|
||||
|
||||
## 测试
|
||||
|
||||
### 运行所有测试
|
||||
|
||||
```bash
|
||||
# 运行所有测试
|
||||
go test -v ./...
|
||||
|
||||
# 仅运行服务层单元测试
|
||||
cd services && go test -v -cover
|
||||
|
||||
# 仅运行集成测试
|
||||
go test -v ./tests/...
|
||||
```
|
||||
|
||||
### 生成测试覆盖率报告
|
||||
|
||||
```bash
|
||||
# 生成覆盖率报告
|
||||
go test -v ./services/... -coverprofile=coverage.out
|
||||
go tool cover -html=coverage.out
|
||||
```
|
||||
|
||||
### 当前测试覆盖
|
||||
|
||||
- **services/**: 包含 AuthService 和 SerialsService 的完整单元测试
|
||||
- 用户认证测试（登录、获取用户信息、修改密码、更新资料）
|
||||
- 序列号管理测试（生成、查询、更新、吊销、分页列表）
|
||||
- **tests/**: 集成测试（健康检查、登录流程）
|
||||
|
||||
## 代码检查
|
||||
|
||||
使用 golangci-lint 进行代码检查：
|
||||
|
||||
```bash
|
||||
golangci-lint run ./...
|
||||
```
|
||||
|
||||
## 部署
|
||||
|
||||
### 编译为二进制文件
|
||||
|
||||
```bash
|
||||
# Linux/Mac
|
||||
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o trace-backend
|
||||
|
||||
# Windows
|
||||
go build -o trace-backend.exe main.go
|
||||
|
||||
# macOS
|
||||
CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build -o trace-backend
|
||||
```
|
||||
|
||||
### 运行
|
||||
|
||||
```bash
|
||||
./trace-backend
|
||||
```
|
||||
|
||||
## 数据库迁移
|
||||
|
||||
### SQLite 到 PostgreSQL 的迁移
|
||||
|
||||
1. 修改配置文件 `config.yaml` 中的数据库驱动：
|
||||
|
||||
```yaml
|
||||
database:
|
||||
driver: postgres
|
||||
postgres:
|
||||
host: localhost
|
||||
port: 5432
|
||||
user: trace
|
||||
password: trace123
|
||||
dbname: trace
|
||||
sslmode: disable
|
||||
```
|
||||
|
||||
2. 或者使用环境变量：
|
||||
|
||||
```bash
|
||||
DATABASE_DRIVER=postgres \
|
||||
POSTGRES_HOST=localhost \
|
||||
POSTGRES_PORT=5432 \
|
||||
POSTGRES_USER=trace \
|
||||
POSTGRES_PASSWORD=trace123 \
|
||||
POSTGRES_DB=trace \
|
||||
POSTGRES_SSLMODE=disable \
|
||||
./trace-backend
|
||||
```
|
||||
|
||||
## 贡献指南
|
||||
|
||||
1. 克隆项目
|
||||
2. 创建新功能分支
|
||||
3. 提交更改
|
||||
4. 推送到远程仓库
|
||||
5. 创建 Pull Request
|
||||
|
||||
### 代码风格要求
|
||||
|
||||
- 使用 gofmt 自动格式化代码
|
||||
- 遵循 Go 官方编码规范
|
||||
- 使用 golangci-lint 进行代码检查
|
||||
- 保持代码简洁和高效
|
||||
|
||||
## 许可证
|
||||
|
||||
MIT License
|
||||
Reference in New Issue
Block a user