TYAPI Server

基于 DDD 和 Clean Architecture 的企业级后端 API 服务，采用 Gin 框架构建，支持用户管理、JWT 认证、企业认证、财务管理等功能。

🚀 快速开始

启动服务

# 开发模式启动
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

📋 功能特性

• 🔐 用户认证: 支持密码登录和短信验证码登录
• 👤 用户管理: 用户注册、信息管理、密码修改
• 👨‍💼 管理员系统: 管理员认证和权限管理
• 🏢 企业认证: 企业信息认证、营业执照上传、人脸验证
• 💰 财务管理: 钱包管理、充值提现、交易记录
• 🔑 密钥管理: 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 (可选)

安装依赖

# 安装 Go 依赖
go mod download
go mod tidy

# 安装开发工具
go install github.com/swaggo/swag/cmd/swag@latest

数据库迁移

# 运行数据库迁移
make migrate

更新 API 文档

# 使用 Makefile
make docs

# 使用 PowerShell 脚本 (Windows)
.\scripts\update-docs.ps1

# 更新文档并重启服务器
.\scripts\update-docs.ps1 -Restart

🐳 Docker 部署

# 开发环境
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)

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)

app:
    env: "production"

database:
    host: "prod-db.example.com"
    password: "prod_secure_password"

运行时

# 使用开发环境配置
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 文档使用指南
• 开发指南
• 架构设计文档
• 部署指南

🤝 贡献指南

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 文件了解详情。