文件即路由

apiDir 下的每个文件就是一个路由。第一层目录是 HTTP 方法，文件路径就是 URL；不需要在一个中央文件里登记路由。

text

src/api/
  index.ts                 由 align 生成
  get/
    index.ts               由 align 生成
    health.ts              GET /health
    user/
      [id].ts              GET /user/:id
  post/
    index.ts               由 align 生成
    user/
      login.ts             POST /user/login

[id] 表示一个路由参数，运行时写作 :id。
处理函数文件必须 export default。
types/handler.d.ts 目前为 get、post、patch、delete 四种方法提供类型投影；运行时本身只是展开方法目录的键，其他方法目录同样会被注册。

生成的汇总导出文件

每个方法目录有一个 index.*，API 根目录再有一个聚合所有方法：

// src/api/get/index.ts
// @generated by tealina — do not edit.
// Rebuild it with: tealina align

export default {
  health: import('./health.js'),
  'user/:id': import('./user/[id].js'),
}

// src/api/index.ts
export default {
  get: import('./get/index.js'),
  post: import('./post/index.js'),
}

键是逻辑路径：不带前导斜杠。@tealina/server 在注册路由时会补上 /。

这些 index.* 是生成物，永远不要手改。文件开头的 // @generated by tealina — do not edit. 就是标记。新增、重命名或删除处理函数后，运行一次 align。

命令

`create`

bash

tealina create post/user       # 写入 src/api/post/user.ts
tealina create user/login      # 未写方法时默认 post
tealina create post/user/:id   # 写成 [id].ts

create 同时更新本次涉及的汇总导出文件。路由段写成 :id 或 [id] 都可以，落盘时统一为 [id]。

`delete`

bash

tealina delete post/user/login
tealina delete post/user/login --with-test

删除处理函数并重写汇总导出文件。--with-test 会一并删除生成的集成测试文件。

`align`

根据磁盘上实际存在的文件，重建所有生成的 index.* 和兜底的 types/api.d.ts。手工移动或重命名文件后，这是必须运行的一条命令。

bash

tealina align
tealina align --check          # 只比较，不写入；有差异时退出码 1
tealina align --check --json   # 标准输出写一个 JSON 对象

--json 的形状：

json

{
  "ok": false,
  "changed": [{ "action": "update", "file": "src/api/get/index.ts" }]
}

--check 适合放进 CI；它和正常执行走同一套生成逻辑，只是在写入前停下。

排除文件

exclude 中的模式相对 apiDir，按 POSIX 路径规则匹配。align 本身已经跳过 index 文件和点文件，这个选项用于其他希望与路由放在一起、但不成为端点的文件：

export default defineConfig({
  apiDir: 'src/api',
  apiBaseURL: '/api/v1',
  typesDir: 'types',
  exclude: ['_shared/**', '**/*.test.ts'],
})

URL 前缀

apiBaseURL 是路由对外回答的前缀，CLI 不会从目录名推断它。在脚手架里它来自 version.js 的 API_BASE_URL，并被至少四处读取：

tealina.config.ts，交给 gdoc；
src/mount.ts，决定路由挂载位置；
src/doc.ts，决定文档 JSON 文件的 URL；
前端 api/client.ts，决定请求 URL 和 Vite 代理。

改前缀时改 version.js，不要分别改这四处。

文件即路由 ​

生成的汇总导出文件 ​

命令 ​

create ​

delete ​

align ​

排除文件 ​

URL 前缀 ​

相关命令的退出码 ​

文件即路由

生成的汇总导出文件

命令

`create`

`delete`

`align`

排除文件

URL 前缀

相关命令的退出码