241 lines
6.0 KiB
Markdown
241 lines
6.0 KiB
Markdown
# TYAPI Server
|
||
|
||
基于 DDD 和 Clean Architecture 的企业级后端 API 服务，采用 Gin 框架构建，支持用户管理、JWT 认证、企业认证、财务管理等功能。
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 启动服务
|
||
|
||
```bash
|
||
# 开发模式启动
|
||
make dev
|
||
|
||
# 或者直接运行
|
||
go run cmd/api/main.go
|
||
```
|
||
|
||
### API 文档
|
||
|
||
启动服务后，可以通过以下地址访问 API 文档：
|
||
|
||
- **Swagger UI**: http://localhost:8080/swagger/index.html
|
||
- **API 文档信息**: http://localhost:8080/api/docs
|
||
- **重定向地址**: http://localhost:8080/docs
|
||
|
||
详细的 API 文档使用说明请参考：[docs/swagger/README.md](docs/swagger/README.md)
|
||
|
||
## 📋 功能特性
|
||
|
||
- 🔐 **用户认证**: 支持密码登录和短信验证码登录
|
||
- 👤 **用户管理**: 用户注册、信息管理、密码修改
|
||
- 👨💼 **管理员系统**: 管理员认证和权限管理
|
||
- 🏢 **企业认证**: 企业信息认证、营业执照上传、人脸验证
|
||
- 💰 **财务管理**: 钱包管理、充值提现、交易记录
|
||
- 🔑 **密钥管理**: API 访问密钥的创建和管理
|
||
- 📊 **监控统计**: 完整的业务数据统计和分析
|
||
|
||
## 🏗️ 技术架构
|
||
|
||
- **框架**: Gin (Go Web Framework)
|
||
- **架构**: DDD + Clean Architecture
|
||
- **数据库**: PostgreSQL + GORM
|
||
- **缓存**: Redis
|
||
- **认证**: JWT
|
||
- **文档**: Swagger/OpenAPI
|
||
- **依赖注入**: Uber FX
|
||
- **日志**: Zap
|
||
- **配置**: Viper
|
||
|
||
## 📁 项目结构
|
||
|
||
```
|
||
tyapi-server-gin/
|
||
├── cmd/api/ # 应用入口
|
||
├── internal/ # 内部包
|
||
│ ├── app/ # 应用层
|
||
│ ├── application/ # 应用服务层
|
||
│ ├── config/ # 配置管理
|
||
│ ├── container/ # 依赖注入容器
|
||
│ ├── domains/ # 领域层
|
||
│ ├── infrastructure/ # 基础设施层
|
||
│ └── shared/ # 共享组件
|
||
├── docs/swagger/ # API 文档
|
||
├── scripts/ # 脚本文件
|
||
└── deployments/ # 部署配置
|
||
```
|
||
|
||
## 🔧 开发指南
|
||
|
||
### 环境要求
|
||
|
||
- Go 1.23+
|
||
- PostgreSQL 12+
|
||
- Redis 6+
|
||
- Docker (可选)
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
# 安装 Go 依赖
|
||
go mod download
|
||
go mod tidy
|
||
|
||
# 安装开发工具
|
||
go install github.com/swaggo/swag/cmd/swag@latest
|
||
```
|
||
|
||
### 数据库迁移
|
||
|
||
```bash
|
||
# 运行数据库迁移
|
||
make migrate
|
||
```
|
||
|
||
### 更新 API 文档
|
||
|
||
```bash
|
||
# 使用 Makefile
|
||
make docs
|
||
|
||
# 使用 PowerShell 脚本 (Windows)
|
||
.\scripts\update-docs.ps1
|
||
|
||
# 更新文档并重启服务器
|
||
.\scripts\update-docs.ps1 -Restart
|
||
```
|
||
|
||
## 🐳 Docker 部署
|
||
|
||
```bash
|
||
# 开发环境
|
||
docker-compose -f docker-compose.dev.yml up -d
|
||
|
||
# 生产环境
|
||
docker-compose -f docker-compose.prod.yml up -d
|
||
```
|
||
|
||
## 📝 配置系统
|
||
|
||
TYAPI 服务端采用分层配置系统，使配置管理更加灵活和清晰：
|
||
|
||
1. **基础配置文件** (`config.yaml`): 包含所有配置项和默认值
|
||
2. **环境特定配置文件** (`configs/env.<环境>.yaml`): 包含特定环境需要覆盖的配置项
|
||
3. **环境变量**: 可以覆盖任何配置项，优先级最高
|
||
|
||
### 配置文件格式
|
||
|
||
所有配置文件采用 YAML 格式，保持相同的结构层次。
|
||
|
||
#### 基础配置文件 (config.yaml)
|
||
|
||
包含所有配置项和默认值，作为配置的基础。
|
||
|
||
#### 环境配置文件
|
||
|
||
环境配置文件只需包含需要覆盖的配置项，保持与基础配置相同的层次结构：
|
||
|
||
- `configs/env.development.yaml`: 开发环境配置
|
||
- `configs/env.testing.yaml`: 测试环境配置
|
||
- `configs/env.production.yaml`: 生产环境配置
|
||
|
||
### 配置加载顺序
|
||
|
||
系统按以下顺序加载配置，后加载的会覆盖先加载的：
|
||
|
||
1. 首先加载基础配置文件 `config.yaml`
|
||
2. 然后加载环境特定配置文件 `configs/env.<环境>.yaml`
|
||
3. 最后应用环境变量覆盖
|
||
|
||
### 环境确定方式
|
||
|
||
系统按以下优先级确定当前环境：
|
||
|
||
1. `CONFIG_ENV` 环境变量
|
||
2. `ENV` 环境变量
|
||
3. `APP_ENV` 环境变量
|
||
4. 默认值 `development`
|
||
|
||
### 统一配置项
|
||
|
||
某些配置项在所有环境中保持一致，直接在基础配置文件中设置：
|
||
|
||
1. **短信配置**: 所有环境使用相同的短信服务配置
|
||
2. **基础服务地址**: 如第三方服务端点等
|
||
|
||
### 使用示例
|
||
|
||
#### 基础配置 (config.yaml)
|
||
|
||
```yaml
|
||
app:
|
||
name: "TYAPI Server"
|
||
version: "1.0.0"
|
||
env: "development"
|
||
|
||
database:
|
||
host: "localhost"
|
||
port: "5432"
|
||
user: "postgres"
|
||
password: "default_password"
|
||
|
||
# 统一的短信配置
|
||
sms:
|
||
access_key_id: "LTAI5tKGB3TVJbMHSoZN3yr9"
|
||
access_key_secret: "OCQ30GWp4yENMjmfOAaagksE18bp65"
|
||
endpoint_url: "dysmsapi.aliyuncs.com"
|
||
```
|
||
|
||
#### 环境配置 (configs/env.production.yaml)
|
||
|
||
```yaml
|
||
app:
|
||
env: "production"
|
||
|
||
database:
|
||
host: "prod-db.example.com"
|
||
password: "prod_secure_password"
|
||
```
|
||
|
||
#### 运行时
|
||
|
||
```bash
|
||
# 使用开发环境配置
|
||
go run cmd/api/main.go
|
||
|
||
# 使用生产环境配置
|
||
ENV=production go run cmd/api/main.go
|
||
|
||
# 使用环境变量覆盖特定配置
|
||
ENV=production DB_PASSWORD=custom_password go run cmd/api/main.go
|
||
```
|
||
|
||
### 敏感信息处理
|
||
|
||
对于敏感信息（如密码、密钥等）：
|
||
|
||
1. 开发环境：可以放在环境配置文件中
|
||
2. 生产环境：应通过环境变量注入，不应出现在配置文件中
|
||
|
||
### 配置验证
|
||
|
||
系统在启动时会验证必要的配置项，确保应用能够正常运行。如果缺少关键配置，系统将拒绝启动并提供明确的错误信息。
|
||
|
||
## 📚 相关文档
|
||
|
||
- [API 文档使用指南](docs/swagger/README.md)
|
||
- [开发指南](docs/开始指南/开发指南.md)
|
||
- [架构设计文档](docs/开始指南/架构设计文档.md)
|
||
- [部署指南](docs/开始指南/部署指南.md)
|
||
|
||
## 🤝 贡献指南
|
||
|
||
1. Fork 本仓库
|
||
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
|
||
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
|
||
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
||
5. 打开 Pull Request
|
||
|
||
## 📄 许可证
|
||
|
||
本项目采用 Apache 2.0 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。
|