455 lines
11 KiB
Markdown
455 lines
11 KiB
Markdown
# Yinli API
|
||
|
||
基于 Golang Gin 框架构建的高性能 RESTful API 服务，集成了 JWT 认证、Redis 缓存、频率限制、CORS 等安全特性。
|
||
|
||
## 🚀 技术架构
|
||
|
||
### 核心技术栈
|
||
|
||
- **Web 框架**: [Gin](https://gin-gonic.com/) - 高性能的 HTTP Web 框架
|
||
- **数据库**: [MySQL 8.0](https://dev.mysql.com/doc/) - 关系型数据库
|
||
- **缓存**: [Redis](https://redis.io/) - 内存数据库，用于缓存和频率限制
|
||
- **ORM**: [GORM](https://gorm.io/) - Go 语言 ORM 库
|
||
- **配置管理**: [Viper](https://github.com/spf13/viper) - 配置文件管理
|
||
- **认证**: [JWT](https://jwt.io/) - JSON Web Token 认证
|
||
- **文档**: [Swagger](https://swagger.io/) - API 文档自动生成
|
||
- **测试**: [Testify](https://github.com/stretchr/testify) - 测试框架
|
||
- **容器化**: [Docker](https://www.docker.com/) - 容器化部署
|
||
|
||
### 安全特性
|
||
|
||
- **JWT 认证**: 基于 JSON Web Token 的用户认证
|
||
- **CORS 支持**: 跨域资源共享配置
|
||
- **频率限制**: 基于 Redis 的 API 频率限制
|
||
- **密码加密**: 使用 bcrypt 加密用户密码
|
||
- **中间件保护**: 多层中间件安全防护
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
yinli-api/
|
||
├── src/ # 源代码目录
|
||
│ ├── main.go # 应用程序入口
|
||
│ ├── handler/ # HTTP 处理器
|
||
│ ├── middleware/ # 中间件
|
||
│ ├── model/ # 数据模型
|
||
│ ├── repository/ # 数据访问层
|
||
│ ├── service/ # 业务逻辑层
|
||
│ └── pkg/ # 可复用的包
|
||
│ ├── auth/ # 认证相关
|
||
│ ├── cache/ # 缓存操作
|
||
│ ├── config/ # 配置管理
|
||
│ └── database/ # 数据库连接
|
||
├── config/ # 配置文件
|
||
│ ├── dev.yaml # 开发环境配置
|
||
│ ├── stage.yaml # 预发布环境配置
|
||
│ └── prod.yaml # 生产环境配置
|
||
├── docker/ # Docker 相关文件
|
||
├── doc/ # API 文档
|
||
├── sql/ # 数据库脚本
|
||
├── test/ # 测试文件
|
||
├── build/ # 构建输出
|
||
├── Dockerfile # Docker 镜像构建文件
|
||
├── Makefile # 构建脚本
|
||
└── README.md # 项目说明
|
||
```
|
||
|
||
## 🛠️ 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Go 1.21+
|
||
- MySQL 8.0+
|
||
- Redis 6.0+
|
||
- Docker & Docker Compose (可选)
|
||
|
||
### 本地开发
|
||
|
||
1. **克隆项目**
|
||
```bash
|
||
git clone <repository-url>
|
||
cd yinli-api
|
||
```
|
||
|
||
2. **安装依赖**
|
||
```bash
|
||
make deps
|
||
```
|
||
|
||
3. **配置数据库**
|
||
```bash
|
||
# 创建数据库
|
||
mysql -u root -p < sql/init.sql
|
||
```
|
||
|
||
4. **启动 Redis**
|
||
```bash
|
||
redis-server
|
||
```
|
||
|
||
5. **启动开发环境**
|
||
```bash
|
||
make dev
|
||
```
|
||
|
||
### Docker 部署
|
||
|
||
1. **生成 Docker Compose 文件**
|
||
```bash
|
||
make docker-compose-dev
|
||
```
|
||
|
||
2. **启动服务**
|
||
```bash
|
||
make docker-up-dev
|
||
```
|
||
|
||
## 📋 可用命令
|
||
|
||
### 开发命令
|
||
|
||
```bash
|
||
make dev # 启动开发环境
|
||
make stage # 启动预发布环境
|
||
make prod # 启动生产环境
|
||
```
|
||
|
||
### 构建命令
|
||
|
||
```bash
|
||
make build # 构建 Linux 版本
|
||
make build-all # 构建所有平台版本
|
||
make clean # 清理构建文件
|
||
```
|
||
|
||
### 测试命令
|
||
|
||
```bash
|
||
make test # 运行测试
|
||
make test-coverage # 运行测试并生成覆盖率报告
|
||
make benchmark # 运行基准测试
|
||
```
|
||
|
||
### 代码质量
|
||
|
||
```bash
|
||
make fmt # 格式化代码
|
||
make vet # 静态检查
|
||
make lint # 代码规范检查
|
||
make check # 执行所有检查
|
||
```
|
||
|
||
### 文档生成
|
||
|
||
```bash
|
||
make docs # 生成 API 文档
|
||
make docs-serve # 启动文档服务器
|
||
```
|
||
|
||
### Docker 操作
|
||
|
||
```bash
|
||
make docker-build # 构建 Docker 镜像
|
||
make docker-up-dev # 启动开发环境容器
|
||
make docker-up-stage # 启动预发布环境容器
|
||
make docker-up-prod # 启动生产环境容器
|
||
make docker-down # 停止容器
|
||
make docker-logs # 查看容器日志
|
||
```
|
||
|
||
## 🔧 配置说明
|
||
|
||
### 环境配置
|
||
|
||
项目支持三种环境配置：
|
||
|
||
- `dev` - 开发环境
|
||
- `stage` - 预发布环境
|
||
- `prod` - 生产环境
|
||
|
||
配置文件位于 `config/` 目录下，可通过环境变量 `APP_ENV` 或命令行参数 `-env` 指定。
|
||
|
||
### 主要配置项
|
||
|
||
```yaml
|
||
server:
|
||
port: 1234 # 服务端口
|
||
mode: debug # 运行模式 (debug/release)
|
||
|
||
database:
|
||
host: localhost # 数据库地址
|
||
port: 3306 # 数据库端口
|
||
username: root # 数据库用户名
|
||
password: sasasasa # 数据库密码
|
||
dbname: yinli # 数据库名称
|
||
|
||
redis:
|
||
host: localhost # Redis 地址
|
||
port: 6379 # Redis 端口
|
||
password: "" # Redis 密码
|
||
db: 0 # Redis 数据库
|
||
|
||
jwt:
|
||
secret: your-secret-key # JWT 密钥
|
||
expireHours: 24 # 令牌过期时间(小时)
|
||
|
||
rateLimit:
|
||
enabled: true # 是否启用频率限制
|
||
requests: 100 # 每个时间窗口的请求数
|
||
window: 60 # 时间窗口(秒)
|
||
```
|
||
|
||
## 📡 API 接口
|
||
|
||
### 认证接口
|
||
|
||
| 方法 | 路径 | 描述 | 认证 |
|
||
|------|------|------|------|
|
||
| POST | `/api/auth/register` | 用户注册 | ❌ |
|
||
| POST | `/api/auth/login` | 用户登录 | ❌ |
|
||
|
||
### 用户接口
|
||
|
||
| 方法 | 路径 | 描述 | 认证 |
|
||
|------|------|------|------|
|
||
| GET | `/api/user/profile` | 获取用户资料 | ✅ |
|
||
| PUT | `/api/user/profile` | 更新用户资料 | ✅ |
|
||
| PUT | `/api/user/password` | 修改密码 | ✅ |
|
||
|
||
### 管理员接口
|
||
|
||
| 方法 | 路径 | 描述 | 认证 |
|
||
|------|------|------|------|
|
||
| GET | `/api/admin/users` | 获取用户列表 | ✅ (管理员) |
|
||
| DELETE | `/api/admin/users/{id}` | 删除用户 | ✅ (管理员) |
|
||
| PUT | `/api/admin/users/{id}/status` | 更新用户状态 | ✅ (管理员) |
|
||
|
||
### 系统接口
|
||
|
||
| 方法 | 路径 | 描述 | 认证 |
|
||
|------|------|------|------|
|
||
| GET | `/health` | 健康检查 | ❌ |
|
||
| GET | `/swagger/*` | API 文档 | ❌ |
|
||
|
||
## 🧪 接口测试
|
||
|
||
### 使用 curl 测试
|
||
|
||
1. **用户注册**
|
||
```bash
|
||
curl -X POST http://localhost:1234/api/auth/register \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"name": "testuser",
|
||
"password": "password123"
|
||
}'
|
||
```
|
||
|
||
2. **用户登录**
|
||
```bash
|
||
curl -X POST http://localhost:1234/api/auth/login \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"name": "testuser",
|
||
"password": "password123"
|
||
}'
|
||
```
|
||
|
||
3. **获取用户资料**
|
||
```bash
|
||
curl -X GET http://localhost:1234/api/user/profile \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||
```
|
||
|
||
### 使用 Postman
|
||
|
||
1. 导入 Postman 集合文件（如果有）
|
||
2. 设置环境变量 `base_url` 为 `http://localhost:1234`
|
||
3. 在认证接口获取 JWT token
|
||
4. 在需要认证的接口中添加 `Authorization: Bearer {token}` 头
|
||
|
||
## 🔍 开发调试
|
||
|
||
### 日志查看
|
||
|
||
```bash
|
||
# 查看应用日志
|
||
tail -f logs/app.log
|
||
|
||
# 查看 Docker 容器日志
|
||
make docker-logs
|
||
```
|
||
|
||
### 数据库调试
|
||
|
||
```bash
|
||
# 连接数据库
|
||
mysql -h localhost -u root -p yinli
|
||
|
||
# 查看用户表
|
||
SELECT * FROM user;
|
||
```
|
||
|
||
### Redis 调试
|
||
|
||
```bash
|
||
# 连接 Redis
|
||
redis-cli
|
||
|
||
# 查看所有键
|
||
KEYS *
|
||
|
||
# 查看频率限制
|
||
KEYS rate_limit:*
|
||
```
|
||
|
||
### 性能监控
|
||
|
||
```bash
|
||
# 查看应用性能
|
||
go tool pprof http://localhost:1234/debug/pprof/profile
|
||
|
||
# 内存使用情况
|
||
go tool pprof http://localhost:1234/debug/pprof/heap
|
||
```
|
||
|
||
### 端口进程管理
|
||
|
||
在 Ubuntu 环境中，如果端口被占用，可以使用以下命令查找并终止进程：
|
||
|
||
```bash
|
||
# 方法1: 使用 netstat 查找端口对应的进程
|
||
netstat -tuln | grep :1234
|
||
|
||
# 方法2: 使用 lsof 查找端口对应的进程（需要安装: sudo apt install lsof）
|
||
lsof -i :1234
|
||
|
||
# 方法3: 使用 ss 查找端口对应的进程
|
||
ss -tulnp | grep :1234
|
||
|
||
# 获取进程 ID (PID) 后，使用以下命令终止进程
|
||
kill <PID>
|
||
|
||
# 如果进程无法正常终止，可以使用强制终止
|
||
kill -9 <PID>
|
||
|
||
# 或者使用一行命令直接终止占用端口的进程
|
||
kill $(lsof -t -i:1234)
|
||
|
||
# 如果 lsof 不可用，可以使用 fuser（需要安装: sudo apt install psmisc）
|
||
sudo fuser -k 1234/tcp
|
||
```
|
||
|
||
**示例：**
|
||
```bash
|
||
# 1. 查找端口 1234 对应的进程
|
||
$ netstat -tulnp | grep :1234
|
||
tcp6 0 0 :::1234 :::* LISTEN 449736/main
|
||
|
||
# 2. 或者使用 lsof 获取更详细信息
|
||
$ lsof -i :1234
|
||
COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
|
||
main 449736 table 9u IPv6 903989 0t0 TCP *:1234 (LISTEN)
|
||
|
||
# 3. 终止进程（PID 为 449736）
|
||
$ kill 449736
|
||
|
||
# 4. 如果进程无法正常终止，使用强制终止
|
||
$ kill -9 449736
|
||
```
|
||
|
||
## 📊 测试报告
|
||
|
||
运行测试并生成报告：
|
||
|
||
```bash
|
||
make test-coverage
|
||
```
|
||
|
||
测试报告将生成在 `build/coverage.html`，可在浏览器中查看详细的覆盖率信息。
|
||
|
||
## 🚀 部署指南
|
||
|
||
### 生产环境部署
|
||
|
||
1. **构建生产版本**
|
||
```bash
|
||
make build
|
||
```
|
||
|
||
2. **配置生产环境**
|
||
```bash
|
||
# 修改 config/prod.yaml
|
||
# 设置正确的数据库和 Redis 连接信息
|
||
# 更改 JWT 密钥
|
||
```
|
||
|
||
3. **使用 Docker 部署**
|
||
```bash
|
||
make docker-compose-prod
|
||
make docker-up-prod
|
||
```
|
||
|
||
### 环境变量
|
||
|
||
生产环境建议使用环境变量覆盖敏感配置：
|
||
|
||
```bash
|
||
export YINLI_DATABASE_PASSWORD=your_db_password
|
||
export YINLI_JWT_SECRET=your_jwt_secret
|
||
export YINLI_REDIS_PASSWORD=your_redis_password
|
||
```
|
||
|
||
## 📚 主要依赖库
|
||
|
||
### 核心依赖
|
||
|
||
- [Gin Web Framework](https://github.com/gin-gonic/gin) - HTTP Web 框架
|
||
- [GORM](https://github.com/go-gorm/gorm) - ORM 库
|
||
- [Viper](https://github.com/spf13/viper) - 配置管理
|
||
- [JWT-Go](https://github.com/golang-jwt/jwt) - JWT 实现
|
||
- [Go-Redis](https://github.com/go-redis/redis) - Redis 客户端
|
||
|
||
### 中间件
|
||
|
||
- [Gin-CORS](https://github.com/gin-contrib/cors) - CORS 中间件
|
||
- [Gin-Swagger](https://github.com/swaggo/gin-swagger) - Swagger 文档
|
||
|
||
### 测试工具
|
||
|
||
- [Testify](https://github.com/stretchr/testify) - 测试断言库
|
||
- [HTTP Test](https://golang.org/pkg/net/http/httptest/) - HTTP 测试工具
|
||
|
||
### 开发工具
|
||
|
||
- [Air](https://github.com/cosmtrek/air) - 热重载工具
|
||
- [GolangCI-Lint](https://github.com/golangci/golangci-lint) - 代码检查工具
|
||
|
||
## 🤝 贡献指南
|
||
|
||
1. Fork 项目
|
||
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
|
||
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
|
||
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
||
5. 开启 Pull Request
|
||
|
||
## 📄 许可证
|
||
|
||
本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。
|
||
|
||
## 🆘 常见问题
|
||
|
||
### Q: 如何修改数据库连接？
|
||
A: 修改 `config/{env}.yaml` 文件中的 `database` 配置项。
|
||
|
||
### Q: 如何添加新的 API 接口？
|
||
A: 1. 在 `src/handler` 中添加处理函数
|
||
2. 在 `src/handler/router.go` 中注册路由
|
||
3. 添加相应的测试用例
|
||
|
||
### Q: 如何自定义中间件？
|
||
A: 在 `src/middleware` 目录下创建新的中间件文件，参考现有中间件的实现。
|
||
|
||
### Q: 如何部署到生产环境？
|
||
A: 使用 `make docker-compose-prod` 生成生产环境配置，然后使用 `make docker-up-prod` 部署。
|