---
title: '**/*.[tj]s'
sidebar_position: 1
---
# **/*.[tj]s

在 [BFF 函数写法](/guides/advanced-features/bff/type.html#函数写法)下，声明 API 路由的文件。除了[某些约定文件](/apis/app/hooks/api/api#白名单)外，`api` 目录下的文件会被注册为接口的路由。

:::info
使用 `api` 目录需要开启 BFF 功能，需要在项目下执行 new 命令启用「BFF」功能。

该文件支持使用 `js` 或 `ts` 语言，但必须使用 `esm` 语法导出函数。

:::

## 该文件约定路由如下：

### 默认路由

路由系统会将以 `index` 命名的文件会被映射到上一层目录。

- `api/index.ts` -> `$BASENAME/`
- `api/user/index.ts` -> `$BASENAME/user`

### 嵌套路由

路由系统也支持解析嵌套的文件，如果创建嵌套文件夹结构，文件仍会以相同方式自动解析路由。

- `api/hello.ts` -> `$BASENAME/hello`
- `api/user/list.ts` -> `$BASENAME/user/list`

### 动态路由

路由系统支持通过 `[]` 命名的文件目录生成动态路由。

- `api/user/[username]/info.ts` -> `$BASENAME/user/:username/info`
- `api/user/[username]/delete.ts` -> `$BASENAME/user/:username/delete`
- `api/article/[id]/info.ts` -> `$BASENAME/article/:id/info`

其中的 `$BASENAME` 可以在 `modern.config.js` 中进行配置，默认值为 `/api`。

### 白名单

默认 `api` 目录下所有文件都会当作 BFF 函数文件去解析，但同样我们也设置了白名单，这些文件不被被解析：

- 命名以 `_` 开头的文件。例如：`_utils.ts`。
- 命名以 `_` 开头的文件夹下所有文件。例如：`_utils/index.ts`、`_utils/cp.ts`。
- 测试文件。例如：`foo.test.ts`。
- TypeScript 类型文件。例如：`hello.d.ts`。
- `node_module` 下的文件。

## 函数定义

除了上面的路由规则之外，代码中函数定义与导出也有相应的约定。

函数通过具名导出，导出函数的名字为对应接口接受的 HTTP Method，即：

```ts
export const get = async () => {
  return {
    name: 'Modern.js',
    desc: '现代 web 工程方案',
  };
};
```

这样导出函数，则会得到一个 `GET` 接口。

应用工程中支持了 9 个 Method 定义，即：`GET`、`POST`、`PUT`、`DELETE`、`CONNECT`、`TRACE`、`PATCH`、`OPTION`、`HEAD`，即可以用这些 Method 作为函数导出的名字。

名字是大小不敏感的，就是说，如果是 `GET`，写成 `get`、`Get`、`GEt`、`GET`，都可以准确识别。而默认导出，即 `export default xxx` 则会被映射为 `Get`。

因为 `delete` 是 JavaScript 中的关键字，可以使用 `del` 或者 `DELETE` 代替。

可以在一个文件中定义多个不同 Method 的函数，但如果定义多个相同 Method 的函数，则只有第一个会生效。

:::info
需要注意的是，定义的函数都应该是异步的，这个与函数调用时类型有关。

:::
