Initial commit: Basic project structure and dependencies
This commit is contained in:
334
README.md
Normal file
334
README.md
Normal file
@@ -0,0 +1,334 @@
|
||||
# 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. 克隆项目
|
||||
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd tyapi-server-gin
|
||||
```
|
||||
|
||||
### 2. 安装依赖
|
||||
|
||||
```bash
|
||||
make deps
|
||||
```
|
||||
|
||||
### 3. 配置环境
|
||||
|
||||
```bash
|
||||
# 创建环境变量文件
|
||||
make env
|
||||
|
||||
# 编辑 .env 文件，配置数据库连接等信息
|
||||
vim .env
|
||||
```
|
||||
|
||||
### 4. 启动依赖服务（Docker）
|
||||
|
||||
```bash
|
||||
# 启动 PostgreSQL, Redis 等服务
|
||||
make services-up
|
||||
```
|
||||
|
||||
### 5. 数据库迁移
|
||||
|
||||
```bash
|
||||
# 运行数据库迁移
|
||||
make migrate
|
||||
```
|
||||
|
||||
### 6. 启动应用
|
||||
|
||||
```bash
|
||||
# 开发模式
|
||||
make dev
|
||||
|
||||
# 或构建后运行
|
||||
make build
|
||||
make run
|
||||
```
|
||||
|
||||
## 🛠️ 开发指南
|
||||
|
||||
### Make 命令
|
||||
|
||||
```bash
|
||||
# 开发相关
|
||||
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` - 系统信息
|
||||
|
||||
### 配置说明
|
||||
|
||||
主要配置项说明：
|
||||
|
||||
```yaml
|
||||
# 应用配置
|
||||
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 中间件**: 跨域请求处理
|
||||
- **安全中间件**: 安全头部设置
|
||||
|
||||
## 📊 监控和运维
|
||||
|
||||
### 健康检查
|
||||
|
||||
```bash
|
||||
# 应用健康检查
|
||||
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 日志，支持不同级别：
|
||||
|
||||
```bash
|
||||
# 查看实时日志
|
||||
make logs
|
||||
|
||||
# 或直接查看文件
|
||||
tail -f logs/app.log
|
||||
```
|
||||
|
||||
## 🧪 测试
|
||||
|
||||
### 运行测试
|
||||
|
||||
```bash
|
||||
# 所有测试
|
||||
make test
|
||||
|
||||
# 生成覆盖率报告
|
||||
make coverage
|
||||
|
||||
# 性能测试
|
||||
make bench
|
||||
|
||||
# 竞态条件检测
|
||||
make race
|
||||
```
|
||||
|
||||
### 测试结构
|
||||
|
||||
- **单元测试**: 业务逻辑测试
|
||||
- **集成测试**: 数据库集成测试
|
||||
- **API 测试**: HTTP 接口测试
|
||||
|
||||
## 🚢 部署
|
||||
|
||||
### Docker 部署
|
||||
|
||||
```bash
|
||||
# 构建镜像
|
||||
make docker-build
|
||||
|
||||
# 运行容器
|
||||
make docker-run
|
||||
```
|
||||
|
||||
### 生产环境
|
||||
|
||||
1. 配置生产环境变量
|
||||
2. 使用 `config.prod.yaml`
|
||||
3. 设置适当的资源限制
|
||||
4. 配置负载均衡和反向代理
|
||||
|
||||
## 🤝 贡献指南
|
||||
|
||||
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) 文件。
|
||||
|
||||
## 🆘 支持
|
||||
|
||||
如有问题或建议，请：
|
||||
|
||||
1. 查看 [文档](docs/)
|
||||
2. 创建 [Issue](issues)
|
||||
3. 参与 [讨论](discussions)
|
||||
|
||||
---
|
||||
|
||||
**TYAPI Server** - 构建下一代 Web 应用的理想选择 🚀
|
||||
Reference in New Issue
Block a user