|
|
@@ -44,4 +44,72 @@ src/
|
|
|
|
|
|
4. **数据库规范**
|
|
|
- 使用迁移脚本管理表结构变更
|
|
|
- - 实体类与数据库表严格映射
|
|
|
+ - 实体类与数据库表严格映射
|
|
|
+
|
|
|
+5. **Hono OpenAPI规范**
|
|
|
+ - 使用`@hono/zod-openapi`的`createRoute`创建路由
|
|
|
+ - 每个路由必须包含:
|
|
|
+ - 请求方法(method)和路径(path)
|
|
|
+ - 请求体验证(使用Zod模式):
|
|
|
+ ```typescript
|
|
|
+ request: {
|
|
|
+ body: {
|
|
|
+ content: {
|
|
|
+ 'application/json': {
|
|
|
+ schema: YourZodSchema
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+ ```
|
|
|
+ - 响应定义(必须包含200/400/500等状态码):
|
|
|
+ ```typescript
|
|
|
+ responses: {
|
|
|
+ 200: {
|
|
|
+ description: '成功响应描述',
|
|
|
+ content: {
|
|
|
+ 'application/json': {
|
|
|
+ schema: SuccessSchema
|
|
|
+ }
|
|
|
+ }
|
|
|
+ },
|
|
|
+ 400: {
|
|
|
+ description: '客户端错误',
|
|
|
+ content: {
|
|
|
+ 'application/json': {
|
|
|
+ schema: ErrorSchema
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+ ```
|
|
|
+ - 错误响应必须使用统一格式:
|
|
|
+ ```typescript
|
|
|
+ {
|
|
|
+ code: number, // HTTP状态码
|
|
|
+ message: string // 错误描述
|
|
|
+ }
|
|
|
+ ```
|
|
|
+ - 实际响应必须与OpenAPI定义完全一致
|
|
|
+ - 使用中间件统一处理错误格式
|
|
|
+ - 示例完整路由定义:
|
|
|
+ ```typescript
|
|
|
+ const route = createRoute({
|
|
|
+ method: 'post',
|
|
|
+ path: '/example',
|
|
|
+100| request: {
|
|
|
+101| body: {
|
|
|
+102| content: {
|
|
|
+103| 'application/json': {
|
|
|
+104| schema: ExampleSchema
|
|
|
+105| }
|
|
|
+106| }
|
|
|
+107| }
|
|
|
+108| },
|
|
|
+109| responses: {
|
|
|
+110| 200: { /*...*/ },
|
|
|
+111| 400: { /*...*/ },
|
|
|
+112| 500: { /*...*/ }
|
|
|
+113| }
|
|
|
+114| });
|
|
|
+115| ```
|
yourname