cevio/hile-http

@hile/http SKILL

本文档用于规范 AI 与开发者在 @hile/http 中的实现方式，确保控制器形式、路由加载与服务生命周期管理一致。

1. 架构概览

@hile/http 由四部分组成：

• Http：封装 Koa 与路由器，负责中间件、路由注册与服务启停
• defineController：将方法、可选中间件与处理函数封装为标准控制器；可选配合 createControllerMetadata 与 Zod 校验 query / params / request.body
• defineResponsePlugin：注册控制器结果的后处理插件链
• Loader：支持手动编译路由与按文件系统自动加载，并提供冲突策略与冲突回调

典型流程：定义控制器 → 加载路由 → 启动服务。

2. 关键类型

import type { Context, Middleware } from 'koa'
import type { HTTPMethod } from 'find-my-way'
import { z, type ZodObject, type ZodType } from 'zod'

type HttpProps = {
  port: number
  keys?: string[]
  ignoreDuplicateSlashes?: boolean
  ignoreTrailingSlash?: boolean
  maxParamLength?: number
  allowUnsafeRegex?: boolean
  caseSensitive?: boolean
}

type ControllerContext<A extends ZodObject, B extends ZodObject, C extends ZodType> = Context & {
  query: z.infer<A>
  params: z.infer<B>
  request: Context['request'] & { body: z.infer<C> }
}

type ControllerFunction<A extends ZodObject, B extends ZodObject, C extends ZodType> = (
  ctx: ControllerContext<A, B, C>
) => unknown | Promise<unknown>
// 两参/三参 defineController(method, …) 内部使用占位 z.object({})，运行时跳过 Zod；handler 仍按 (ctx: Context) 书写即可

type ResponsePluginFunction = (
  ctx: Context,
  result: any,
  next: (r: any) => Promise<void>
) => Promise<any>

interface ControllerRegisterProps {
  id: number
  method: HTTPMethod
  middlewares: Middleware[]
  data: Record<string, any>
}

type LoaderConflictStrategy = 'error' | 'warn' | 'override'
type LoaderConflictResolution = 'error' | 'keep' | 'override'

type LoaderConflictContext = {
  routeKey: string
  method: string
  url: string
  strategy: LoaderConflictStrategy
  resolution: LoaderConflictResolution
}

interface LoaderCompileOptions {
  defaultSuffix?: string
  prefix?: string
  conflict?: LoaderConflictStrategy
  onConflict?: (ctx: LoaderConflictContext) => void
}

type LoaderFromOptions = {
  suffix?: string
} & LoaderCompileOptions

3. 标准模板

3.1 创建 Http 实例

import { Http } from '@hile/http'

const http = new Http({ port: 3000 })

listen(onListen?)：可选 onListen(server) 在 createServer 之后、server.listen 完成端口绑定之前调用（可为 async），便于把同一 http.Server 交给 Next.js、WebSocket 等；返回 Promise<() => void> 关闭函数。

3.2 注册全局中间件

http.use(async (ctx, next) => {
  const start = Date.now()
  await next()
  ctx.set('X-Response-Time', `${Date.now() - start}ms`)
})

规则：必须在 listen() 前调用。

3.3 手动注册路由

const off = http.get('/api/users', async (ctx) => {
  ctx.body = { users: [] }
})

off()

规则：所有路由注册方法都返回注销函数。另支持 patch(url, ...mw) 与通用 route(method, url, ...mw)。

3.4 定义控制器

无中间件：

import { defineController } from '@hile/http'

export default defineController('GET', async (ctx) => {
  return { ok: true }
})

带中间件：

import { defineController } from '@hile/http'

const auth = async (ctx, next) => {
  if (!ctx.headers.authorization) ctx.throw(401)
  await next()
}

export default defineController('POST', [auth], async (ctx) => {
  return { created: true }
})

规则：

• 控制器文件必须 export default
• 控制器函数签名为 (ctx)，不是 (ctx, next)
• 控制器返回值会先经过响应插件链
• 插件链最终结果非 undefined 时自动写入 ctx.body

使用 createControllerMetadata 声明 Zod schema 时，走第三重载 defineController(metadata, fn)；请求进入控制器前对 ctx.query、ctx.params、ctx.request.body 分别 safeParse，失败 ctx.throw(400, message)。仅声明部分字段（如只写 body）时，未声明部分不校验。schema 的三项均为内部占位空对象时与旧版行为一致（跳过校验）。

import { z } from 'zod'
import { createControllerMetadata, defineController } from '@hile/http'

const meta = createControllerMetadata({
  method: 'POST',
  middlewares: [],
  schema: {
    query: z.object({ page: z.coerce.number().optional() }),
    params: z.object({ id: z.string().uuid() }),
    body: z.object({ title: z.string().min(1) }),
  },
})

export default defineController(meta, async (ctx) => {
  return { id: ctx.params.id, title: ctx.request.body.title, page: ctx.query.page }
})

3.5 响应插件

import { defineResponsePlugin } from '@hile/http'

defineResponsePlugin(async (ctx, result, next) => {
  if (ctx.path.endsWith('.json')) {
    return await next({ data: result })
  }
  return await next(result)
})

规则：

• 插件按注册顺序串行执行
• 插件必须调用 next(transformedResult) 以传递结果
• 若最终传给 next 的结果为 undefined，不会设置 ctx.body

3.6 文件系统自动路由

await http.load('./src/controllers', {
  suffix: 'controller',
  defaultSuffix: '/index',
  prefix: '/api',
  conflict: 'warn',
  onConflict: (ctx) => {
    console.warn('route conflict', ctx)
  },
})

文件路径映射示例：

| 文件路径 | 路由路径 | |---|---| | index.controller.ts | /api | | users/index.controller.ts | /api/users | | users/[id].controller.ts | /api/users/:id |

冲突策略说明：

• error：同一 method + path 冲突时抛错（默认）
• warn：保留旧路由并发出警告
• override：新路由覆盖旧路由

onConflict 会在发生冲突时回调，提供 routeKey/method/url/strategy/resolution。

from() 会校验控制器默认导出类型。若导出不合法，错误信息包含文件路径和导出摘要，便于定位。

4. 强制规则

1. 全局中间件必须在 listen() 前注册。
2. 控制器必须 default 导出。
3. 控制器文件命名使用 *.controller.ts/js（或与 suffix 一致）。
4. 需要多个 HTTP 方法时，default 导出数组。
5. 控制器里不要调用 next()，需要 next 的逻辑放中间件。
6. load() 为异步，必须 await。
7. 大型项目建议显式设置 conflict 策略，避免隐式覆盖。
8. 使用 Zod 时，schema 应与真实请求形状一致；校验失败为 400，消息来自 Zod。

5. 常见反模式

控制器中调用 next

// ✗
export default defineController('GET', async (ctx, next) => {
  await next()
  return { ok: true }
})

// ✓
export default defineController('GET', async (ctx) => {
  return { ok: true }
})

重复设置响应

// ✗
export default defineController('GET', async (ctx) => {
  ctx.body = { a: 1 }
  return { b: 2 }
})

// ✓
export default defineController('GET', async () => {
  return { b: 2 }
})

不配置冲突策略导致行为不清晰

// ✗ 不清晰：项目多人协作时难以统一预期
await http.load('./src/controllers')

// ✓ 显式策略：可读且可审计
await http.load('./src/controllers', { conflict: 'error' })

6. 与 @hile/core 集成

import { defineService } from '@hile/core'
import { Http } from '@hile/http'

export const httpService = defineService('http', async (shutdown) => {
  const http = new Http({ port: 3000 })
  await http.load('./src/controllers', { suffix: 'controller', prefix: '/api' })

  const close = await http.listen()
  shutdown(close)

  return http
})

7. API 速查

| 导出 | 说明 | |---|---| | Http | HTTP 服务实例类（listen(onListen?)、get/post/put/delete/patch/trace/route、load） | | defineController | 控制器定义（method+fn、method+middlewares+fn、metadata+fn） | | createControllerMetadata | 构造带 method / middlewares / schema 的元数据，供 Zod 校验 | | ControllerContext | 带推断类型的 Context（类型） | | defineResponsePlugin | 响应结果插件 | | Loader | 路由加载器 | | compileRoutePath | 路径编译纯函数 | | toRouterPath | 参数路径转换纯函数 |