feat(架构): 完善基础架构设计

2025-07-02 16:17:59 +08:00
parent 03e615a8fd
commit 5b4392894f
89 changed files with 18555 additions and 3521 deletions
--- a/README.md
+++ b/README.md
@@ -1,334 +1,107 @@
-# TYAPI Server
+# TYAPI 服务端配置系统

-## 🚀 2025 年最前沿的 Go Web 架构系统
+## 配置系统设计

-TYAPI Server 是一个基于 Go 语言和 Gin 框架构建的现代化、高性能、模块化的 Web API 服务器。采用领域驱动设计(DDD)、CQRS、事件驱动架构等先进设计模式，为企业级应用提供坚实的技术基础。
+TYAPI 服务端采用分层配置系统，使配置管理更加灵活和清晰：

-## ✨ 核心特性
+1. **基础配置文件** (`config.yaml`): 包含所有配置项和默认值
+2. **环境特定配置文件** (`configs/env.<环境>.yaml`): 包含特定环境需要覆盖的配置项
+3. **环境变量**: 可以覆盖任何配置项，优先级最高

-### 🏗️ 架构特性
+## 配置文件格式

-   **领域驱动设计(DDD)**: 清晰的业务边界和模型隔离
-   **CQRS 模式**: 命令查询责任分离，优化读写性能
-   **事件驱动**: 基于事件的异步处理和系统解耦
-   **依赖注入**: 基于 Uber FX 的完整 IoC 容器
-   **模块化设计**: 高内聚、低耦合的组件架构
+所有配置文件采用 YAML 格式，保持相同的结构层次。

-### 🔧 技术栈
+### 基础配置文件 (config.yaml)

-   **Web 框架**: Gin (高性能 HTTP 路由)
-   **ORM**: GORM (功能强大的对象关系映射)
-   **数据库**: PostgreSQL (主数据库) + Redis (缓存)
-   **日志**: Zap (结构化高性能日志)
-   **配置**: Viper (多格式配置管理)
-   **监控**: Prometheus + Grafana + Jaeger
-   **依赖注入**: Uber FX
+包含所有配置项和默认值，作为配置的基础。

-### 🛡️ 生产就绪特性
+### 环境配置文件

-   **安全性**: JWT 认证、CORS、安全头部、输入验证
-   **性能**: 智能缓存、连接池、限流、压缩
-   **可观测性**: 链路追踪、指标监控、结构化日志
-   **容错性**: 熔断器、重试机制、优雅降级
-   **运维**: 健康检查、优雅关闭、Docker 化部署
+环境配置文件只需包含需要覆盖的配置项，保持与基础配置相同的层次结构：

-## 📁 项目结构
+-   `configs/env.development.yaml`: 开发环境配置
+-   `configs/env.testing.yaml`: 测试环境配置
+-   `configs/env.production.yaml`: 生产环境配置

-```
-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              # 项目说明
-```
+## 配置加载顺序

-## 🚀 快速开始
+系统按以下顺序加载配置，后加载的会覆盖先加载的：

-### 环境要求
+1. 首先加载基础配置文件 `config.yaml`
+2. 然后加载环境特定配置文件 `configs/env.<环境>.yaml`
+3. 最后应用环境变量覆盖

-   Go 1.23.4+
-   PostgreSQL 12+
-   Redis 6+
-   Docker & Docker Compose (可选)
+## 环境确定方式

-### 1. 克隆项目
+系统按以下优先级确定当前环境：

-```bash
-git clone <repository-url>
-cd tyapi-server-gin
-```
+1. `CONFIG_ENV` 环境变量
+2. `ENV` 环境变量
+3. `APP_ENV` 环境变量
+4. 默认值 `development`

-### 2. 安装依赖
+## 统一配置项

-```bash
-make deps
-```
+某些配置项在所有环境中保持一致，直接在基础配置文件中设置：

-### 3. 配置环境
+1. **短信配置**: 所有环境使用相同的短信服务配置
+2. **基础服务地址**: 如第三方服务端点等

-```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` - 系统信息
-
-### 配置说明
-
-主要配置项说明：
+### 基础配置 (config.yaml)

 ```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"
+    password: "default_password"

-# JWT配置
-jwt:
-    secret: "your-secret-key"
-    expires_in: 24h
+# 统一的短信配置
+sms:
+    access_key_id: "LTAI5tKGB3TVJbMHSoZN3yr9"
+    access_key_secret: "OCQ30GWp4yENMjmfOAaagksE18bp65"
+    endpoint_url: "dysmsapi.aliyuncs.com"
 ```

-## 🏗️ 架构说明
+### 环境配置 (configs/env.production.yaml)

-### 领域驱动设计
+```yaml
+app:
+    env: "production"

-项目采用 DDD 架构模式，每个业务域包含：
+database:
+    host: "prod-db.example.com"
+    password: "prod_secure_password"
+```

-   **Entities**: 业务实体，包含业务逻辑
-   **DTOs**: 数据传输对象，用于 API 交互
-   **Services**: 业务服务，协调实体完成业务操作
-   **Repositories**: 仓储模式，抽象数据访问
-   **Events**: 域事件，实现模块间解耦
-
-### 事件驱动架构
-
-   **事件总线**: 异步事件分发机制
-   **事件处理器**: 响应特定事件的处理逻辑
-   **事件存储**: 事件溯源和审计日志
-
-### 中间件系统
-
-   **认证中间件**: JWT token 验证
-   **限流中间件**: API 调用频率控制
-   **日志中间件**: 请求/响应日志记录
-   **CORS 中间件**: 跨域请求处理
-   **安全中间件**: 安全头部设置
-
-## 📊 监控和运维
-
-### 健康检查
+### 运行时

 ```bash
-# 应用健康检查
-curl http://localhost:8080/health
+# 使用开发环境配置
+go run cmd/api/main.go

-# 系统信息
-curl http://localhost:8080/info
+# 使用生产环境配置
+ENV=production go run cmd/api/main.go
+
+# 使用环境变量覆盖特定配置
+ENV=production DB_PASSWORD=custom_password go run cmd/api/main.go
 ```

-### 指标监控
+## 敏感信息处理

-   **Prometheus**: `http://localhost:9090`
-   **Grafana**: `http://localhost:3000` (admin/admin)
-   **Jaeger**: `http://localhost:16686`
+对于敏感信息（如密码、密钥等）：

-### 日志管理
+1. 开发环境：可以放在环境配置文件中
+2. 生产环境：应通过环境变量注入，不应出现在配置文件中

-结构化 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 应用的理想选择 🚀
+系统在启动时会验证必要的配置项，确保应用能够正常运行。如果缺少关键配置，系统将拒绝启动并提供明确的错误信息。