nitro-api-development

# Nitro v3 接口开发技能规范

本技能用于指导使用 Nitro v3 框架编写服务端接口，包括项目初始化、配置、接口编写规范等完整流程。

## 1. 适用场景

- **纯后端 Nitro 项目初始化**：对非 Vite 的 Node.js 项目，初始化 Nitro 示例代码和配置
- **Vite 项目全栈化**：对 Vite 项目，初始化 Nitro 接口和配置，赋予全栈能力
- **接口开发与维护**：按规范编写 Nitro v3 格式的接口代码

## 2. 核心依赖

```bash
# Nitro v3 核心包
pnpm add nitro

# 可选：日志工具
pnpm add consola
```

## 3. 目录结构规范

Nitro 支持两种目录结构，根据项目规模选择：

### 3.1 扁平结构（推荐用于小型项目）

```plain
project-root/
├── server/                          # Nitro 服务端目录
│   ├── routes/                      # API 路由目录
│   │   ├── users.get.ts             # GET /users
│   │   ├── users.post.ts            # POST /users
│   │   └── health.get.ts            # GET /health
│   └── db/                          # 数据库相关（可选）
│       └── index.ts
├── nitro.config.ts                  # Nitro 配置文件
└── package.json
```

### 3.2 模块化结构（适用于大型项目）

```plain
project-root/
├── server/                          # Nitro 服务端目录
│   ├── api/                         # API 接口目录
│   │   └── {module}/{feature}/
│   │       ├── list.post.ts         # 列表查询接口
│   │       └── [id].get.ts          # 详情接口
│   └── utils/                       # 工具函数（可选）
│       └── filter-data.ts
├── nitro.config.ts                  # Nitro 配置文件
└── package.json
```

**文件路径映射规则**：文件路径直接映射为 API 路径

```plain
文件: server/routes/users.get.ts     -> GET /users
文件: server/api/users/list.post.ts  -> POST /api/users/list
```

## 4. 核心规范 [CRITICAL]

### 4.1 导入模块规范

```typescript
// 必须从 nitro/h3 导入，不是 h3
import { defineHandler, readBody } from "nitro/h3";

// 类型导入（根据项目实际定义）
import type { UserItem, QueryParams } from "./types";
```

### 4.2 基础接口模板

```typescript
/**
 * @file 用户列表接口
 * @description User list API
 * GET /users
 */

import { defineHandler } from "nitro/h3";

export default defineHandler(async (event) => {
	return {
		success: true,
		data: [
			{ id: "1", name: "John" },
			{ id: "2", name: "Jane" },
		],
	};
});
```

### 4.3 带参数的接口模板

```typescript
/**
 * @file 创建用户接口
 * @description Create user API
 * POST /users
 */

import { defineH