API 接口
API 架构
MuseMVP 的 API 总览：为什么选 Hono、如何在 Next.js 接入，以及可用性与观测入口。
MuseMVP 使用 Hono + Next.js Route Handler 组合：所有 API 统一走 /api/*，并由 Hono 管理路由与中间件。
Overview
src/app/api/[[...rest]]/route.ts
src/backend/api/app.ts
src/backend/api/routes/
请求链路保持单一入口：/api/* -> route.ts -> Hono app.ts -> feature router -> service/query。
Why Hono
选择 Hono 的原因很直接：
- 轻量，路由与中间件组织清晰
- TypeScript 友好，便于构建类型安全 API Client
- 易于集成 OpenAPI，方便接口协作
相比把逻辑分散在多个 Route Handler，集中式 API 层更容易维护。
Availability
默认情况下，API 与 Web 一起对外提供，不需要维护两套入口。
如果后续接入移动端、插件或第三方客户端，也可以复用这套 Hono 路由。
常见路由组（示例）：
/api（auth）/api/admin、/api/aichat、/api/upload/api/muse-billing、/api/upgrade、/api/newsletter/api/health/api/openapi、/api/docs
分层约定：
- Route：参数校验、权限、HTTP 响应
- Service（
src/modules/<feature>/lib/*）：业务编排 - Query（
src/backend/database/queries/*）：数据库读写
Observability
- 健康检查：
/api/health - OpenAPI：
/api/openapi - API 文档（Scalar UI）：
/api/docs
实践建议
中间件只做入口职责（日志、跨域、鉴权门禁）；复杂业务逻辑放到 service 层，避免 API 入口层膨胀。