# 后端

应用可以带一个后端: 一个导出 `fetch` 的模块, 或任何调 `listen()` 的 Node.js / Bun 服务器 (Express、Hono、Fastify ……). 页面用普通的 `fetch('/api/…')` 访问它.

应用后端在 macOS、Linux 和 Windows 上都能跑. Windows 上运行时用另一种方式连到后端; 见 [Windows 上](#windows-上).

## 写一个后端

`acdev new my-app --backend` 生成的 `server.ts`:

```ts
export default {
  fetch(request: Request): Response {
    const url = new URL(request.url)
    if (url.pathname === '/api/hello') return Response.json({ hello: 'world', at: new Date().toISOString() })
    return new Response('not found', { status: 404 })
  },
}
```

页面里:

```js
const answer = await (await fetch('/api/hello')).json()
```

`export default { fetch }` 在 Bun 和 Node.js 上都能用: Node.js 上 acdev 的 preload 用 `node:http` 把它跑起来, 请求和回应都是 WHATWG 的 `Request` / `Response`, 支持流式 body. (Node.js 上没有 WebSocket 升级.)

也可以自己 listen:

```ts
import { createServer } from 'node:http'

createServer((req, res) => res.end('hi')).listen(3000)
```

## 后端出页面

要让后端自己渲染页面 (用 Hono、JSX、模板 ……在服务端生成 HTML, 不用 acdev 认得的框架), 把入口设成 `/`:

```jsonc
{ "type": "app", "id": "my-app", "label": "My app", "icon": "app", "entry": "/" }
```

这时窗口从后端打开 `/`, 它跳到的每个页面 (链接、`location.href`、表单) 也都来自后端; `public/` 仍然在应用的根路径下提供. 没有后端时, `acdev check` 和 `acdev build` 报错停下; 以 `/` 结尾的入口只接受 `/` 这一个. 在服务端渲染的框架 (Next.js、Nuxt、SvelteKit ……) 自动这样设置; 见 [前端框架](https://docs.dopame.ai/zh/guide/frameworks.md).

## 入口

不写 `backend` 时, acdev 按顺序找第一个存在的:

`server.ts` `server.js` `src/server.ts` `src/server.js` `server/index.ts` `server/index.js` `backend/index.ts` `backend/index.js`

显式指定, 或关掉:

```jsonc
{ "backend": { "entry": "api/main.ts", "port": 8080 } }
{ "backend": false }
```

`port` 默认 3000, 是后端以为自己在听的端口.

## 后端不占 TCP 端口

应用的后端不在宿主机上开 TCP 端口. 构建时 acdev 在后端旁放一个 preload (`acde-listen.js`), 它把 `Bun.serve`、`Bun.listen` 和 `net` / `http` / `https` / `tls` / `http2` 的 `listen(P)` 都换成一个 unix socket `<应用的 socket 目录>/P.sock`. 没给端口时取 `PORT` / `BUN_PORT` / `NODE_PORT`, 否则用 3000.

所以:

- 两个应用都 `listen(3000)` 不会冲突.
- 页面访问同源的路径 (`/api/x`), 或 `http://localhost:<端口>/…` (以及 `127.0.0.1`、`[::1]`、`0.0.0.0`), 都会送到自己的后端.
- 指定端口的 UDP `bind` 会被拒绝 (`EACCES`); 原生扩展自己开的端口不受此限制.

## Windows 上

同一份构建产物在 Windows 上也能跑, 那里后端同样不开 TCP 端口, 也不开命名管道. 运行时怎么连到它, 看是什么在跑它:

- **Bun**: 和 macOS、Linux 上一样, `listen(P)` 变成一个 socket 文件 `P.sock`. 它所在的目录 (`ACDE_APP_SOCKETS`) 每次启动后端时重新建, 只有当前用户和系统能打开.
- **Node.js**: Node.js 在 Windows 上不能听 socket 文件, 所以根本没有东西在听. preload 留住调了 `listen(P)` 的那个服务器, 运行时通过一条通到后端进程的私有管道, 把每个连接 (HTTP 请求和 WebSocket 升级) 交给它. 后端拿到 `ACDE_APP_CHANNEL=fd`, 没有 `ACDE_APP_SOCKETS`. 在这之前的 acdev 构建的后端在 Windows 上不会被启动; 日志里写 `not started: acde-listen.js does not support the Windows channel (built by an older acde: acdev build it again)`.

在 Windows 上停后端时, 运行时请它自己关闭: 它不再接新连接, 做完进行中的请求, 然后退出; 3 秒后运行时结束它, 连同它启动的进程.

## 打包

`acdev build` 把后端打成单个 ES 模块 `backend/server.js` (target node): npm 包打进去, Node 内置模块和 `bun` / `bun:*` 保留为导入. Bun 和 Node.js 都能跑同一份产物.

## 运行

- 应用的**第一个窗口打开时**启动后端, **最后一个窗口关掉时**停掉 (macOS 和 Linux 上先 SIGTERM, 3 秒后 SIGKILL; Windows 见 [上文](#windows-上)). 一分钟里崩溃第 4 次后不再自动重启.
- PATH 上有 `bun` 时用 Bun 跑, 否则用 Node.js (≥ 22.3). `acdev dev` 按工程的 JS 运行时选.
- 环境变量是新建的: `ACDE_APP_ID`、`ACDE_APP_DATA`、`ACDE_APP_SOCKETS`、`PORT`、`NODE_ENV=production`, 再加会话的 `HOME`、`PATH`、`LANG` 等, 以及下面说的代理变量. 除此之外不会继承你终端里的环境.
- 代理设置会传给后端. 会话里设了 `http_proxy`、`https_proxy`、`all_proxy` 中的任何一个时, 后端拿到会话里的 `http_proxy`、`https_proxy`、`all_proxy` 和 `no_proxy`, 原样不变 (macOS 和 Linux 上小写和大写两种名字都按设的传; Windows 上变量名不分大小写, 用大写的名字). 一个都没设时, 后端拿到系统的手动代理, 和页面用的是同一份设置. 只有 Windows 和 macOS 有这种设置: Windows 上是用户 Internet 设置里的 HTTP 代理 (`socks=` 项变成 `all_proxy=socks4a://host:port`), 用大写的名字设; macOS 上是网络设置里的 HTTP、HTTPS 和 SOCKS 代理 (SOCKS 变成 `socks5h://host:port`), 小写和大写两种名字都设. 这时 `no_proxy` 里是会话的 `no_proxy`、换成 `no_proxy` 写法的系统例外 (`*.example.com` 变成 `.example.com`, `192.168.*` 变成 `192.168.0.0/16`; 其它通配符、Windows 的 `<local>` 和 macOS 的「排除简单主机名」没有 `no_proxy` 的写法, 不带上), 以及 `localhost,127.0.0.1,::1`. 代理自动配置脚本和自动发现代理是按 URL 回答的, 没法写成变量, 所以用它们时后端拿不到系统代理 (Windows 上只勾了「自动检测设置」时, 手动代理照样传). 每次启动后端时读一遍这些设置. Linux 没有可读的系统代理设置: 那里只算会话的变量. 你用的 HTTP 客户端还得自己认这些变量 (Bun 的 `fetch` 和很多 npm 客户端认; Node.js 内置的 `fetch` 默认不认).
- 工作目录是 `$XDG_DATA_HOME/acde/apps/<id>/`, 可以在这里放应用自己的数据.
- 在 macOS 和 Linux 上, socket 放在会话的运行时的一个目录里 (`ACDE_APP_SOCKETS`). 每个会话有自己的目录, 在 acdev 的运行时目录下的 `<运行时的 pid>/<id>`, 后端停了就删掉: macOS 上是 `$TMPDIR/acde-<uid>`, 别处是 `XDG_RUNTIME_DIR` 里的 `acde/` (Linux 上没设时是 `/run/user/<uid>`). socket 路径比系统允许的长 (macOS 104 字节, Linux 108) 时后端不启动, 日志里会说.
- 后端的输出进运行时的日志, 前缀 `[<id>#backend]`. `acdev dev` 会把它打在终端里.

## 直接跑

不经运行时单独调试构建好的后端时, 给它一个 socket 目录, 并载入 `acdev build` 放在它旁边的 preload (下面的命令是 macOS 和 Linux 上的):

```sh
acdev build
cd .acde/backend
ACDE_APP_SOCKETS=/tmp/my-app-sockets bun --preload ./acde-listen.js server.js
curl --unix-socket /tmp/my-app-sockets/3000.sock http://localhost/api/hello
```
