Back to Details

api-route-endpoint

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

API Route/Endpoint Skill

API路由/端点开发规范

Follow existing Hono patterns in apps/api when creating or updating endpoints.

在创建或更新端点时，请遵循apps/api目录中已有的Hono代码模式。

Workflow

工作流程

Identify the feature folder under

apps/api/src/routes

and create or update the three files:

```
routes/<feature>/<feature>.index.ts
```
(route wiring)
```
routes/<feature>/<feature>.handler.ts
```
(handlers)
```
routes/<feature>/<feature>.schema.ts
```
(Zod schemas)

Use
```
createRouter()
```
for route modules and
```
createHandlers()
```
for handlers.
Use
```
validate()
```
from
```
apps/api/src/lib/validator.ts
```
with Zod schemas.
Use
```
initializePrisma(c.env.DATABASE_URL)
```
for database access.
Return JSON with the standard response structure (see references).
Wire middleware for auth/roles where needed.
Register the route in
```
apps/api/src/routes/index.ts
```
if it is a new top-level group.

在
```
apps/api/src/routes
```
下找到对应的功能文件夹，创建或更新以下三个文件：
- ```
routes/<feature>/<feature>.index.ts
```
  （路由配置）
- ```
routes/<feature>/<feature>.handler.ts
```
  （请求处理器）
- ```
routes/<feature>/<feature>.schema.ts
```
  （Zod校验模式）
使用
```
createRouter()
```
创建路由模块，使用
```
createHandlers()
```
定义请求处理器。
结合Zod模式，使用
```
apps/api/src/lib/validator.ts
```
中的
```
validate()
```
方法进行校验。
使用
```
initializePrisma(c.env.DATABASE_URL)
```
进行数据库访问。
按照标准响应结构返回JSON数据（参考相关文档）。
根据需要配置认证/角色权限中间件。
如果是新增的顶级路由组，需要在
```
apps/api/src/routes/index.ts
```
中注册该路由。

Required patterns

必须遵循的规范

Route wiring: use
```
.get
```
,
```
.post
```
,
```
.put
```
,
```
.delete
```
with spread handler arrays:
```
route.get('/', ...getItems)
```
.

Validation:

validate('param' | 'query' | 'json', schema)

as the first handlers in

createHandlers

.

Handler response: return

c.json({ meta: { code, message }, data: { ... } }, code)

.

Errors: map Prisma errors to status codes where appropriate; fall through to app error handler.

路由配置：使用
```
.get
```
、
```
.post
```
、
```
.put
```
、
```
.delete
```
方法，并传入展开的处理器数组，例如：
```
route.get('/', ...getItems)
```
。

校验规则：在

createHandlers

的第一个处理器位置使用

validate('param' | 'query' | 'json', schema)

。

处理器响应：返回

c.json({ meta: { code, message }, data: { ... } }, code)

格式的数据。

错误处理：将Prisma错误映射为对应的状态码；未匹配的错误交由应用全局错误处理器处理。

Middleware

中间件

Use
```
requireAuth
```
for authenticated routes.
Use
```
requireAdminRole
```
for admin-only routes.

对于需要认证的路由，使用
```
requireAuth
```
中间件。
对于仅管理员可访问的路由，使用
```
requireAdminRole
```
中间件。

Response structure

响应结构

Always return

{ meta: { code, message }, data: { ... } }

.

For errors with no payload, return
```
data: {}
```
.

必须返回

{ meta: { code, message }, data: { ... } }

格式的数据。

无返回数据的错误响应，需返回
```
data: {}
```
。

References

参考文档

See
```
references/api-route-patterns.md
```
for concrete file layouts, schema patterns, and response examples.

具体的文件结构、模式示例和响应示例，请参考
```
references/api-route-patterns.md
```
。