Files

D8D Developer 71aaeb9424 ci: 添加 Docker 构建和推送工作流

- 新增 Dockerfile 和 .dockerignore 文件
- 添加 Gitea 持续集成工作流，用于构建和推送 Docker 镜像
- 新增 .gitignore 文件，忽略构建和配置文件
- 添加项目结构和规范文档，包括 TypeScript、模块化、API、数据库等规范
- 新增前端和后端的基础代码结构

2025-06-11 09:35:39 +00:00

3.9 KiB

Raw Blame History

Hono OpenAPI规范

常见不规范问题

路径参数问题:
- ❌ 使用冒号定义路径参数: /:id
- ✅ 必须使用花括号: /{id}
参数Schema缺失:
- ❌ 未定义params Schema
- ✅ 必须定义并添加OpenAPI元数据
参数获取方式:
- ❌ 使用c.req.param()
- ✅ 必须使用c.req.valid('param')
OpenAPI元数据:
- ❌ 路径参数缺少OpenAPI描述
- ✅ 必须包含example和description

核心规范

1. 路由定义

路径参数:

必须使用花括号 {} 定义 (例: /{id})

必须定义 params Schema 并添加 OpenAPI 元数据:

const GetParams = z.object({
  id: z.string().openapi({
    param: { name: 'id', in: 'path' },
    example: '1',
    description: '资源ID'
  })
});

路由定义中必须包含 params 定义:
```
request: { params: GetParams }
```
必须使用 c.req.valid('param') 获取路径参数

请求定义:

request: {
  body: {
    content: {
      'application/json': { schema: YourZodSchema }
    }
  }
}

响应定义:

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

路由示例:

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定义完全一致

处理示例:

try {
  // 业务逻辑
} catch (error) {
  return c.json({ code: 500, message: '操作失败' }, 500);
}

3. dataSource引入

示例:

import { AppDataSource } from '@/server/data-source';

4. service初始化

示例:

import { WorkspaceService } from '@/server/modules/workspaces/workspace.service';
const workspaceService = new WorkspaceService(AppDataSource);

5. 用户context获取

示例:
```
const user = c.get('user');
```
- 注意: 确保 c.get('user') 已经在 authMiddleware 中设置

6. AuthContext引用

示例:

import { AuthContext } from '@/server/types/context';

7. createRoute, OpenAPIHono 引入

示例:

import { createRoute, OpenAPIHono } from '@hono/zod-openapi';

8. ErrorSchema 引入

示例:

import { ErrorSchema } from '@/server/utils/errorHandler';

进阶规范

1. 路由聚合

当多个相关路由需要组合时:

文件结构:
- 拆分为独立文件 (create.ts, list.ts 等)
- 创建 index.ts 聚合所有子路由

实现:

export default {
  createRoute,
  getRoute,
  deleteRoute
}

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

路由文件代码结构规范

+imports: 依赖导入 +serviceInit: 服务初始化 +paramsSchema: 路径参数定义 +responseSchema: 响应定义 +errorSchema: 错误定义 +routeDef: 路由定义 +app: 路由实例

完整示例

// 路由实例
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;

3.9 KiB Raw Blame History