webapp-starter/.roo/rules/07-openapi.md

# Hono OpenAPI规范

## 常见不规范问题
1. **路径参数问题**:
   - ❌ 使用冒号定义路径参数: `/:id`
   - ✅ 必须使用花括号: `/{id}`
    
2. **参数Schema缺失**:
   - ❌ 未定义params Schema
   - ✅ 必须定义并添加OpenAPI元数据

3. **参数获取方式**:
   - ❌ 使用`c.req.param()`
   - ✅ 必须使用`c.req.valid('param')`

4. **OpenAPI元数据**:
   - ❌ 路径参数缺少OpenAPI描述
   - ✅ 必须包含example和description

## 核心规范
### 1. 路由定义
- **路径参数**:
  - 必须使用花括号 `{}` 定义 (例: `/{id}`)
  - 必须定义 params Schema 并添加 OpenAPI 元数据:
    ```typescript
    const GetParams = z.object({
      id: z.string().openapi({
        param: { name: 'id', in: 'path' },
        example: '1',
        description: '资源ID'
      })
    });
    ```
  - 路由定义中必须包含 params 定义:
    ```typescript
    request: { params: GetParams }
    ```
  - 必须使用 `c.req.valid('param')` 获取路径参数

- **请求定义**:
  ```typescript
  request: {
    body: {
      content: {
        'application/json': { schema: YourZodSchema }
      }
    }
  }
  ```

- **响应定义**:
  ```typescript
  responses: {
    200: {
      description: '成功响应描述',
      content: { 'application/json': { schema: SuccessSchema } }
    },
    400: {
      description: '客户端错误',
      content: { 'application/json': { schema: ErrorSchema } }
    },
    500: {
      description: '服务器错误',
      content: { 'application/json': { schema: ErrorSchema } }
    }
  }
  ```

- **路由示例**:
  ```typescript
  const routeDef = createRoute({
    method: 'post',
    path: '/workspaces',
    middleware: authMiddleware,
    request: {
      body: {
        content: { 'application/json': { schema: CreateSchema } }
      }
    },
    responses: {
      200: { ... },
      400: { ... },
      500: { ... }
    }
  });
  ```

### 2. 错误处理
- 错误响应必须使用统一格式: `{ code: number, message: string }`
- 必须与OpenAPI定义完全一致
- 处理示例:
  ```typescript
  try {
    // 业务逻辑
  } catch (error) {
    return c.json({ code: 500, message: '操作失败' }, 500);
  }
  ```

### 3. dataSource引入
- 示例:
  ```typescript
  import { AppDataSource } from '@/server/data-source';
  ```

### 4. service初始化
- 示例:
  ```typescript
  import { WorkspaceService } from '@/server/modules/workspaces/workspace.service';
  const workspaceService = new WorkspaceService(AppDataSource);

### 5. 用户context获取
- 示例:
  ```typescript
  const user = c.get('user');
  ```
  - 注意: 确保 `c.get('user')` 已经在 `authMiddleware` 中设置

### 6. AuthContext引用
- 示例:
  ```typescript
  import { AuthContext } from '@/server/types/context';
  ```

### 7. createRoute, OpenAPIHono 引入
- 示例:
  ```typescript
  import { createRoute, OpenAPIHono } from '@hono/zod-openapi';
  ```

### 8. ErrorSchema 引入
- 示例:
  ```typescript
  import { ErrorSchema } from '@/server/utils/errorHandler';
  ```

## 进阶规范
### 1. 路由聚合
当多个相关路由需要组合时:
1. **文件结构**:
   - 拆分为独立文件 (`create.ts`, `list.ts` 等)
   - 创建 `index.ts` 聚合所有子路由

2. **实现**:
   ```typescript   
   export default {
     createRoute,
     getRoute,
     deleteRoute
   }
   ```

3. **优势**:
   - 保持模块化
   - 简化维护
   - 统一API入口

## 路由文件代码结构规范
  +imports: 依赖导入
  +serviceInit: 服务初始化
  +paramsSchema: 路径参数定义
  +responseSchema: 响应定义
  +errorSchema: 错误定义
  +routeDef: 路由定义
  +app: 路由实例

## 完整示例
```typescript
// 路由实例
const app = new OpenAPIHono<AuthContext>().openapi(routeDef, async (c) => {
  try {
    // 业务逻辑
    return c.json(result, 200);
  } catch (error) {
    return c.json({ code: 500, message: '操作失败' }, 500);
  }
});

export default app;
```