file-starter

常见错误排查指南

前端常见错误

日期组件错误

错误表现:
date4.isValid is not a function
TypeError: date4.isValid is not a function

错误原因:
使用原生Date对象而非dayjs对象初始化日期组件

错误示例:

// 错误示例 - 使用原生Date对象
form.setFieldsValue({
  noteDate: new Date(record.noteDate) // 导致验证失败
});

正确做法:

// 正确示例 - 使用dayjs对象
form.setFieldsValue({
  noteDate: dayjs(record.noteDate) // 正常支持验证方法
});

后端常见错误

OpenAPI路由定义错误

1. 路径参数定义错误

错误表现:
路径参数无法正确解析，接口调用404

错误原因:
使用冒号:定义路径参数而非花括号{}

错误示例:

// 错误方式
path: '/:id'

正确做法:

// 正确方式
path: '/{id}'

2. 参数类型转换错误

错误表现:
数字/布尔型URL参数验证失败，提示类型错误

错误原因:
未使用z.coerce处理URL字符串参数到目标类型的转换

错误示例:

// 错误方式 - 直接使用z.number()
z.number().int().positive() // 无法处理字符串参数

// 错误方式 - 直接使用z.boolean()
z.boolean() // 无法处理字符串参数

正确做法:

// 正确方式 - 使用z.coerce.number()
z.coerce.number().int().positive() // 自动转换字符串参数

// 正确方式 - 使用z.coerce.boolean()
z.coerce.boolean() // 自动转换字符串参数

实体定义错误

1. 创建/更新Schema缺少coerce

错误表现:
日期/数字类型参数验证失败，接口返回400错误

错误原因:
实体的创建/更新Schema中，日期、数字等类型未使用z.coerce进行类型转换

正确做法:

export const UpdateEntityDto = z.object({
  price: z.coerce.number().multipleOf(0.01).optional().openapi({
    description: '价格',
    example: 89.99
  }),
  isActive: z.coerce.boolean().optional().openapi({
    description: '是否激活',
    example: false
  }),
  expireDate: z.coerce.date().optional().openapi({
    description: '过期日期',
    example: '2025-12-31T23:59:59Z'
  })
});

RPC调用错误

InferResponseType使用错误

错误表现:
TypeScript类型推断失败，提示属性不存在

错误原因:
访问带参数的路由类型时未正确使用数组语法

错误示例:

// 错误方式
InferResponseType<typeof zichanClient[':id'].$get, 200>

正确做法:

// 正确方式 - $get要加中括号
InferResponseType<typeof zichanClient[':id']['$get'], 200>

前后端交互错误

表单验证规则不匹配

错误表现:
前端表单提交后后端验证失败，或前端验证通过但后端返回400

错误原因:
前端表单的必填/选填规则与后端实体的create/update schema不一致

正确做法:

1. 前端表单验证规则必须与后端保持一致
2. 后端实体schema变更时需同步更新前端表单验证
3. 创建操作使用CreateXXXDto，更新操作使用UpdateXXXDto