---
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": "张三" }
  }
  ```

---

**请所有开发者严格遵守以上规范，确保接口文档完整、参数校验严格、错误提示友好（中文），提升用户体验与协作效率。**