# 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 应用的理想选择 🚀