expressgy
5b0b37ef78
- Prettier 配置迁移为 .prettierrc.cjs，解决 ESM/CJS 兼容问题 - 优化 package.json，补全元信息、整理依赖、完善 Bun 热更新脚本 - 归档项目初始化 PRD 与任务清单到 tasks/archive，并加日期前缀 - 同步代码风格与格式化配置，提升团队协作一致性 归档文件：tasks/archive/20240610-prd-项目初始化.md, tasks/archive/20240610-tasks-prd-项目初始化.md
110 lines
2.5 KiB
Plaintext
110 lines
2.5 KiB
Plaintext
---
|
||
description:
|
||
globs:
|
||
alwaysApply: true
|
||
---
|
||
# Elysia 后台接口 API 设计与校验规范
|
||
|
||
## 1. 接口文档自动生成（Swagger/OpenAPI）
|
||
- 每个接口必须通过 `@elysiajs/swagger` 插件自动生成 Swagger 文档，便于前后端协作与接口管理。
|
||
- 路由、参数、返回类型、错误码等需在 Swagger 中完整描述。
|
||
- 推荐在开发环境默认启用 Swagger UI。
|
||
|
||
## 2. 参数与返回类型校验
|
||
- 所有接口参数（body、query、params、headers）必须定义类型并进行严格校验。
|
||
- 推荐使用Elysia原生t类型校验库。
|
||
- 校验规则需明确字段必填、类型、长度、格式、范围等。
|
||
- 校验失败时，接口需返回标准 JSON 错误响应，便于用户理解。
|
||
- 返回类型也需定义并校验，保证接口契约。
|
||
|
||
## 3. 错误响应规范
|
||
- 所有参数校验失败、类型不匹配等错误，需统一返回如下结构：
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "error message",
|
||
"data": null
|
||
}
|
||
```
|
||
- 错误码、错误信息需文档化，便于前后端协作。
|
||
- 常见的公共的错误和正常相应，统一放在validators中的global.response.ts
|
||
|
||
|
||
**注意，其他的请求参数和响应验证，在同一批接口下，放在同一个validators文件中**
|
||
|
||
|
||
## 4. 示例代码
|
||
|
||
### 4.1 安装依赖
|
||
```sh
|
||
bun add elysia @elysiajs/swagger valibot
|
||
```
|
||
|
||
### 4.2 接口定义与参数校验
|
||
|
||
```ts
|
||
.get(
|
||
'/note/:index',
|
||
({ note, params: { index } }) => {
|
||
return note.data[index]
|
||
},
|
||
{
|
||
params: t.Object({
|
||
index: t.Number()
|
||
})
|
||
}
|
||
)
|
||
```
|
||
|
||
### 4.3 调用接口示例
|
||
- 请求：
|
||
```json
|
||
POST /api/user
|
||
{
|
||
"name": "A"
|
||
}
|
||
```
|
||
- 响应：
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "姓名长度不能少于2个字符",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
- 请求：
|
||
```json
|
||
POST /api/user
|
||
{
|
||
"name": "张三丰丰丰丰丰丰丰丰"
|
||
}
|
||
```
|
||
- 响应：
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "姓名长度不能超过8个字符",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
- 请求：
|
||
```json
|
||
POST /api/user
|
||
{
|
||
"name": "张三"
|
||
}
|
||
```
|
||
- 响应：
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "创建成功",
|
||
"data": { "name": "张三" }
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
**请所有开发者严格遵守以上规范，确保接口文档完整、参数校验严格、错误提示友好（中文），提升用户体验与协作效率。** |