TYAPI Server
🚀 2025 年最前沿的 Go Web 架构系统
TYAPI Server 是一个基于 Go 语言和 Gin 框架构建的现代化、高性能、模块化的 Web API 服务器。采用领域驱动设计(DDD)、CQRS、事件驱动架构等先进设计模式，为企业级应用提供坚实的技术基础。
✨ 核心特性
🏗️ 架构特性
- 领域驱动设计(DDD): 清晰的业务边界和模型隔离
- CQRS 模式: 命令查询责任分离，优化读写性能
- 事件驱动: 基于事件的异步处理和系统解耦
- 依赖注入: 基于 Uber FX 的完整 IoC 容器
- 模块化设计: 高内聚、低耦合的组件架构
🔧 技术栈
- Web 框架: Gin (高性能 HTTP 路由)
- ORM: GORM (功能强大的对象关系映射)
- 数据库: PostgreSQL (主数据库) + Redis (缓存)
- 日志: Zap (结构化高性能日志)
- 配置: Viper (多格式配置管理)
- 监控: Prometheus + Grafana + Jaeger
- 依赖注入: Uber FX
🛡️ 生产就绪特性
- 安全性: JWT 认证、CORS、安全头部、输入验证
- 性能: 智能缓存、连接池、限流、压缩
- 可观测性: 链路追踪、指标监控、结构化日志
- 容错性: 熔断器、重试机制、优雅降级
- 运维: 健康检查、优雅关闭、Docker 化部署
📁 项目结构
tyapi-server-gin/
├── cmd/ # 应用程序入口
│ └── api/
│ └── main.go # 主程序入口
├── internal/ # 内部代码
│ ├── app/ # 应用启动器
│ ├── config/ # 配置管理
│ ├── container/ # 依赖注入容器
│ ├── domains/ # 业务域
│ │ └── user/ # 用户域
│ │ ├── dto/ # 数据传输对象
│ │ ├── entities/ # 实体
│ │ ├── events/ # 域事件
│ │ ├── handlers/ # HTTP处理器
│ │ ├── repositories/ # 仓储层
│ │ ├── routes/ # 路由定义
│ │ └── services/ # 业务服务
│ └── shared/ # 共享组件
│ ├── cache/ # 缓存服务
│ ├── database/ # 数据库连接
│ ├── events/ # 事件总线
│ ├── health/ # 健康检查
│ ├── http/ # HTTP组件
│ ├── interfaces/ # 接口定义
│ ├── logger/ # 日志服务
│ └── middleware/ # 中间件
├── deployments/ # 部署相关
├── docs/ # 文档
├── scripts/ # 脚本文件
├── test/ # 测试文件
├── config.yaml # 配置文件
├── docker-compose.dev.yml # 开发环境
├── Makefile # 构建脚本
└── README.md # 项目说明
🚀 快速开始
环境要求
- Go 1.23.4+
- PostgreSQL 12+
- Redis 6+
- Docker & Docker Compose (可选)
1. 克隆项目
git clone <repository-url>
cd tyapi-server-gin
2. 安装依赖
make deps
3. 配置环境
# 创建环境变量文件
make env
# 编辑 .env 文件，配置数据库连接等信息
vim .env
4. 启动依赖服务（Docker）
# 启动 PostgreSQL, Redis 等服务
make services-up
5. 数据库迁移
# 运行数据库迁移
make migrate
6. 启动应用
# 开发模式
make dev
# 或构建后运行
make build
make run
🛠️ 开发指南
Make 命令
# 开发相关
make setup # 设置开发环境
make dev # 开发模式运行
make build # 构建应用
make test # 运行测试
make lint # 代码检查
# 数据库相关
make migrate # 运行迁移
make services-up # 启动依赖服务
make services-down # 停止依赖服务
# Docker相关
make docker-build # 构建Docker镜像
make docker-run # 运行Docker容器
# 其他
make clean # 清理构建文件
make help # 显示帮助信息
API 端点
认证相关
POST /api/v1/auth/login- 用户登录POST /api/v1/auth/register- 用户注册
用户管理
GET /api/v1/users- 获取用户列表GET /api/v1/users/:id- 获取用户详情POST /api/v1/users- 创建用户PUT /api/v1/users/:id- 更新用户DELETE /api/v1/users/:id- 删除用户
个人资料
GET /api/v1/profile- 获取个人资料PUT /api/v1/profile- 更新个人资料POST /api/v1/profile/change-password- 修改密码
系统
GET /health- 健康检查GET /info- 系统信息
配置说明
主要配置项说明：
# 应用配置
app:
name: "TYAPI Server"
version: "1.0.0"
env: "development"
# 服务器配置
server:
host: "0.0.0.0"
port: "8080"
# 数据库配置
database:
host: "localhost"
port: "5432"
user: "postgres"
password: "password"
name: "tyapi_dev"
# JWT配置
jwt:
secret: "your-secret-key"
expires_in: 24h
🏗️ 架构说明
领域驱动设计
项目采用 DDD 架构模式，每个业务域包含：
- Entities: 业务实体，包含业务逻辑
- DTOs: 数据传输对象，用于 API 交互
- Services: 业务服务，协调实体完成业务操作
- Repositories: 仓储模式，抽象数据访问
- Events: 域事件，实现模块间解耦
事件驱动架构
- 事件总线: 异步事件分发机制
- 事件处理器: 响应特定事件的处理逻辑
- 事件存储: 事件溯源和审计日志
中间件系统
- 认证中间件: JWT token 验证
- 限流中间件: API 调用频率控制
- 日志中间件: 请求/响应日志记录
- CORS 中间件: 跨域请求处理
- 安全中间件: 安全头部设置
📊 监控和运维
健康检查
# 应用健康检查
curl http://localhost:8080/health
# 系统信息
curl http://localhost:8080/info
指标监控
- Prometheus:
http://localhost:9090 - Grafana:
http://localhost:3000(admin/admin) - Jaeger:
http://localhost:16686
日志管理
结构化 JSON 日志，支持不同级别：
# 查看实时日志
make logs
# 或直接查看文件
tail -f logs/app.log
🧪 测试
运行测试
# 所有测试
make test
# 生成覆盖率报告
make coverage
# 性能测试
make bench
# 竞态条件检测
make race
测试结构
- 单元测试: 业务逻辑测试
- 集成测试: 数据库集成测试
- API 测试: HTTP 接口测试
🚢 部署
Docker 部署
# 构建镜像
make docker-build
# 运行容器
make docker-run
生产环境
- 配置生产环境变量
- 使用
config.prod.yaml - 设置适当的资源限制
- 配置负载均衡和反向代理
🤝 贡献指南
- Fork 项目
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 创建 Pull Request
📝 许可证
本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。
🆘 支持
如有问题或建议，请：
TYAPI Server - 构建下一代 Web 应用的理想选择 🚀