API 开发
Hono.js 路由、中间件和 OpenAPI 文档
架构概览
API 层使用 Hono.js 框架，挂载在 Next.js 的 /api 路径下。
- 入口文件:
apps/web/src/server/app.ts - 路由目录:
apps/web/src/server/routes/ - 中间件:
apps/web/src/server/middleware/
路由组织
路由按功能模块拆分为独立文件，在 app.ts 中统一挂载：
src/server/routes/
├── admin.ts # 管理员接口
├── auth.ts # 认证相关
├── events.ts # 活动 CRUD
├── organizations.ts # 组织管理
├── users.ts # 用户接口
├── contributions.ts # 贡献管理
├── projects.ts # 项目管理
└── ... # 40+ 路由模块创建新 API 路由
- 在
src/server/routes/下创建路由文件：
import { Hono } from "hono";
const app = new Hono()
.get("/", async (c) => {
return c.json({ message: "Hello" });
})
.post("/", async (c) => {
const body = await c.req.json();
return c.json({ data: body });
});
export default app;- 在
src/server/app.ts中挂载：
import myRoute from "./routes/my-route";
app.route("/my-route", myRoute);中间件
| 中间件 | 文件 | 说明 |
|---|---|---|
| CORS | middleware/cors.ts | 跨域请求处理 |
| 错误处理 | middleware/error-handler.ts | 统一错误响应 |
| 限流 | middleware/rate-limit.ts | API 请求频率限制 |
Auth 中间件
在路由中使用认证中间件保护接口：
// 需要登录
app.use("/*", authMiddleware);
// 需要管理员权限
app.use("/*", adminMiddleware);OpenAPI 文档
项目自动生成 OpenAPI 文档，开发时访问：
- Scalar UI: http://localhost:3000/api/docs
API 文档合并了 Hono 路由和 Better Auth 的 OpenAPI schema。
Zod 请求验证
使用 Zod 进行请求体验证：
import { z } from "zod";
import { zValidator } from "@hono/zod-validator";
const schema = z.object({
title: z.string().min(1),
type: z.enum(["MEETUP", "HACKATHON"]),
});
app.post("/", zValidator("json", schema), async (c) => {
const data = c.req.valid("json");
// data 已经过类型校验
});Events Token API
Events Token 是一种专用 API 密钥，用于在飞书、Zapier 等外部工具中自动创建活动。
- 在「账号设置 → 安全」中生成 Token
- 请求头:
Authorization: EventsToken <token> - 限流: 每 Token 每 5 分钟 60 次请求
curl -X POST https://your-domain/api/events \
-H "Authorization: EventsToken evt_xxxxx" \
-H "Content-Type: application/json" \
-d '{ "title": "API meetup", "type": "MEETUP", "isOnline": true }'