377 lines
7.8 KiB
Plaintext
377 lines
7.8 KiB
Plaintext
---
|
||
alwaysApply: true
|
||
---
|
||
|
||
# 🤖 AI友好的Elysia开发规则体系
|
||
|
||
## 快速开始 🚀
|
||
|
||
### 1. 对于开发者
|
||
|
||
**首次使用：**
|
||
1. 阅读 `ai-friendly-elysia-rules.md` 了解规范
|
||
2. 查看 `ai-development-workflow.md` 学习如何与AI协作
|
||
3. 在项目中导入支持文件
|
||
|
||
**日常开发：**
|
||
```typescript
|
||
// 使用标准错误码
|
||
import { ERROR_CODES } from '@/constants/error-codes';
|
||
|
||
// 使用响应工具
|
||
import { successResponse, errorResponse, BusinessError } from '@/utils/response.helper';
|
||
```
|
||
|
||
### 2. 对于AI助手
|
||
|
||
**工作原则：**
|
||
- 严格遵循 `ai-friendly-elysia-rules.md` 规范
|
||
- 按照 `ai-development-workflow.md` 工作流程
|
||
- 确保代码质量和一致性
|
||
|
||
**开发顺序：**
|
||
1. Schema定义（最高优先级）
|
||
2. Response格式
|
||
3. Service层实现
|
||
4. Controller层实现
|
||
5. 测试用例
|
||
|
||
## 核心优势 💪
|
||
|
||
### 1. 一致性
|
||
- 统一的文件结构
|
||
- 标准的命名规范
|
||
- 一致的错误处理
|
||
|
||
### 2. 类型安全
|
||
- TypeBox Schema + TypeScript类型
|
||
- 编译时类型检查
|
||
- 运行时参数验证
|
||
|
||
### 3. 可维护性
|
||
- 清晰的模块划分
|
||
- 完整的文档注释
|
||
- 系统化的测试
|
||
|
||
### 4. AI友好
|
||
- 语义清晰的代码结构
|
||
- 明确的依赖关系
|
||
- 标准化的模式
|
||
|
||
## 使用示例 📝
|
||
|
||
### 创建新模块
|
||
|
||
当你需要创建新的业务模块时，告诉AI助手：
|
||
|
||
```
|
||
功能：用户管理
|
||
模块：user
|
||
接口：注册、登录、获取个人信息、修改个人信息
|
||
认证：登录后的接口需要JWT认证
|
||
特殊要求：密码需要加密存储
|
||
```
|
||
|
||
AI助手会自动创建：
|
||
- `src/modules/user/user.schema.ts`
|
||
- `src/modules/user/user.response.ts`
|
||
- `src/modules/user/user.service.ts`
|
||
- `src/modules/user/user.controller.ts`
|
||
- `src/modules/user/user.test.ts`
|
||
|
||
### 修改现有功能
|
||
|
||
```
|
||
修改用户查询接口，添加分页功能，每页最多50条记录
|
||
```
|
||
|
||
AI助手会：
|
||
1. 分析现有代码
|
||
2. 更新Schema定义
|
||
3. 修改Service逻辑
|
||
4. 更新Controller
|
||
5. 补充测试用例
|
||
|
||
## 代码质量保证 ✅
|
||
|
||
### 自动检查项
|
||
- [ ] TypeScript类型正确性
|
||
- [ ] Schema验证完整性
|
||
- [ ] 错误处理覆盖
|
||
- [ ] 响应格式一致性
|
||
- [ ] 命名规范符合标准
|
||
- [ ] 文档注释完整
|
||
|
||
### 人工Review项
|
||
- [ ] 业务逻辑正确性
|
||
- [ ] 安全性考虑
|
||
- [ ] 性能优化
|
||
- [ ] 用户体验
|
||
|
||
## 最佳实践 🌟
|
||
|
||
### 1. 需求描述
|
||
```
|
||
✅ 清晰：实现用户注册接口，包含邮箱验证和密码强度检查
|
||
❌ 模糊：做一个用户功能
|
||
```
|
||
|
||
### 2. 错误处理
|
||
```typescript
|
||
// ✅ 使用标准错误类
|
||
throw new BusinessError('用户名已存在', ERROR_CODES.USER_ALREADY_EXISTS);
|
||
|
||
// ❌ 直接抛出Error
|
||
throw new Error('用户名已存在');
|
||
```
|
||
|
||
### 3. 响应格式
|
||
```typescript
|
||
// ✅ 使用工具函数
|
||
return successResponse(userData, '查询成功');
|
||
|
||
// ❌ 手动构造
|
||
return { code: 'SUCCESS', message: '查询成功', data: userData };
|
||
```
|
||
|
||
## 性能考虑 ⚡
|
||
|
||
### 数据库优化
|
||
- 使用索引优化查询
|
||
- 避免N+1查询问题
|
||
- 合理使用连接池
|
||
|
||
### 缓存策略
|
||
- 热点数据Redis缓存
|
||
- 适当的缓存过期时间
|
||
- 缓存穿透防护
|
||
|
||
### 并发处理
|
||
- 避免阻塞操作
|
||
- 合理的超时设置
|
||
- 资源清理
|
||
|
||
## 故障排除 🔧
|
||
|
||
### 常见问题
|
||
|
||
1. **类型错误**
|
||
- 检查Schema定义
|
||
- 确认类型导出
|
||
- 验证导入路径
|
||
|
||
2. **运行时错误**
|
||
- 查看错误日志
|
||
- 检查参数验证
|
||
- 确认业务逻辑
|
||
|
||
3. **性能问题**
|
||
- 分析慢查询
|
||
- 检查缓存命中率
|
||
- 监控资源使用
|
||
|
||
### 调试技巧
|
||
|
||
```typescript
|
||
// 添加调试日志
|
||
Logger.debug(`处理用户请求: ${JSON.stringify(params)}`);
|
||
|
||
// 性能监控
|
||
const startTime = Date.now();
|
||
// ... 业务逻辑
|
||
Logger.info(`操作耗时: ${Date.now() - startTime}ms`);
|
||
```
|
||
|
||
## 版本历史 📚
|
||
|
||
- **v1.0.0** - 初始版本，包含核心规范
|
||
- **v1.1.0** - 添加AI协作指南
|
||
- **v1.2.0** - 完善错误处理和响应格式
|
||
|
||
记住：好的规范不是限制，而是让团队更高效协作的基础！ 🎯 # 🤖 AI友好的Elysia开发规则体系
|
||
|
||
## 快速开始 🚀
|
||
|
||
### 1. 对于开发者
|
||
|
||
**首次使用：**
|
||
1. 阅读 `ai-friendly-elysia-rules.md` 了解规范
|
||
2. 查看 `ai-development-workflow.md` 学习如何与AI协作
|
||
3. 在项目中导入支持文件
|
||
|
||
**日常开发：**
|
||
```typescript
|
||
// 使用标准错误码
|
||
import { ERROR_CODES } from '@/constants/error-codes';
|
||
|
||
// 使用响应工具
|
||
import { successResponse, errorResponse, BusinessError } from '@/utils/response.helper';
|
||
```
|
||
|
||
### 2. 对于AI助手
|
||
|
||
**工作原则：**
|
||
- 严格遵循 `ai-friendly-elysia-rules.md` 规范
|
||
- 按照 `ai-development-workflow.md` 工作流程
|
||
- 确保代码质量和一致性
|
||
|
||
**开发顺序：**
|
||
1. Schema定义（最高优先级）
|
||
2. Response格式
|
||
3. Service层实现
|
||
4. Controller层实现
|
||
5. 测试用例
|
||
|
||
## 核心优势 💪
|
||
|
||
### 1. 一致性
|
||
- 统一的文件结构
|
||
- 标准的命名规范
|
||
- 一致的错误处理
|
||
|
||
### 2. 类型安全
|
||
- TypeBox Schema + TypeScript类型
|
||
- 编译时类型检查
|
||
- 运行时参数验证
|
||
|
||
### 3. 可维护性
|
||
- 清晰的模块划分
|
||
- 完整的文档注释
|
||
- 系统化的测试
|
||
|
||
### 4. AI友好
|
||
- 语义清晰的代码结构
|
||
- 明确的依赖关系
|
||
- 标准化的模式
|
||
|
||
## 使用示例 📝
|
||
|
||
### 创建新模块
|
||
|
||
当你需要创建新的业务模块时，告诉AI助手：
|
||
|
||
```
|
||
功能：用户管理
|
||
模块：user
|
||
接口：注册、登录、获取个人信息、修改个人信息
|
||
认证：登录后的接口需要JWT认证
|
||
特殊要求：密码需要加密存储
|
||
```
|
||
|
||
AI助手会自动创建：
|
||
- `src/modules/user/user.schema.ts`
|
||
- `src/modules/user/user.response.ts`
|
||
- `src/modules/user/user.service.ts`
|
||
- `src/modules/user/user.controller.ts`
|
||
- `src/modules/user/user.test.ts`
|
||
|
||
### 修改现有功能
|
||
|
||
```
|
||
修改用户查询接口，添加分页功能，每页最多50条记录
|
||
```
|
||
|
||
AI助手会：
|
||
1. 分析现有代码
|
||
2. 更新Schema定义
|
||
3. 修改Service逻辑
|
||
4. 更新Controller
|
||
5. 补充测试用例
|
||
|
||
## 代码质量保证 ✅
|
||
|
||
### 自动检查项
|
||
- [ ] TypeScript类型正确性
|
||
- [ ] Schema验证完整性
|
||
- [ ] 错误处理覆盖
|
||
- [ ] 响应格式一致性
|
||
- [ ] 命名规范符合标准
|
||
- [ ] 文档注释完整
|
||
|
||
### 人工Review项
|
||
- [ ] 业务逻辑正确性
|
||
- [ ] 安全性考虑
|
||
- [ ] 性能优化
|
||
- [ ] 用户体验
|
||
|
||
## 最佳实践 🌟
|
||
|
||
### 1. 需求描述
|
||
```
|
||
✅ 清晰：实现用户注册接口，包含邮箱验证和密码强度检查
|
||
❌ 模糊：做一个用户功能
|
||
```
|
||
|
||
### 2. 错误处理
|
||
```typescript
|
||
// ✅ 使用标准错误类
|
||
throw new BusinessError('用户名已存在', ERROR_CODES.USER_ALREADY_EXISTS);
|
||
|
||
// ❌ 直接抛出Error
|
||
throw new Error('用户名已存在');
|
||
```
|
||
|
||
### 3. 响应格式
|
||
```typescript
|
||
// ✅ 使用工具函数
|
||
return successResponse(userData, '查询成功');
|
||
|
||
// ❌ 手动构造
|
||
return { code: 'SUCCESS', message: '查询成功', data: userData };
|
||
```
|
||
|
||
## 性能考虑 ⚡
|
||
|
||
### 数据库优化
|
||
- 使用索引优化查询
|
||
- 避免N+1查询问题
|
||
- 合理使用连接池
|
||
|
||
### 缓存策略
|
||
- 热点数据Redis缓存
|
||
- 适当的缓存过期时间
|
||
- 缓存穿透防护
|
||
|
||
### 并发处理
|
||
- 避免阻塞操作
|
||
- 合理的超时设置
|
||
- 资源清理
|
||
|
||
## 故障排除 🔧
|
||
|
||
### 常见问题
|
||
|
||
1. **类型错误**
|
||
- 检查Schema定义
|
||
- 确认类型导出
|
||
- 验证导入路径
|
||
|
||
2. **运行时错误**
|
||
- 查看错误日志
|
||
- 检查参数验证
|
||
- 确认业务逻辑
|
||
|
||
3. **性能问题**
|
||
- 分析慢查询
|
||
- 检查缓存命中率
|
||
- 监控资源使用
|
||
|
||
### 调试技巧
|
||
|
||
```typescript
|
||
// 添加调试日志
|
||
Logger.debug(`处理用户请求: ${JSON.stringify(params)}`);
|
||
|
||
// 性能监控
|
||
const startTime = Date.now();
|
||
// ... 业务逻辑
|
||
Logger.info(`操作耗时: ${Date.now() - startTime}ms`);
|
||
```
|
||
|
||
## 版本历史 📚
|
||
|
||
- **v1.0.0** - 初始版本，包含核心规范
|
||
- **v1.1.0** - 添加AI协作指南
|
||
- **v1.2.0** - 完善错误处理和响应格式
|
||
|
||
记住：好的规范不是限制，而是让团队更高效协作的基础！ 🎯 |