在 Expo SDK 50 中引入 React Native API 路由（RFC 说明）

本 RFC 提议将 API 路由（即服务器功能）引入 React Native 生态系统，作为 Expo Router v3 和即将推出的 Expo SDK 50 的一部分。

目标是让开发者能够在 React Native 项目（支持 iOS、Android 和 Web）中直接编写服务器端逻辑，从而简化开发流程、提升安全性并改善开发者体验。

一. 动机

在移动应用开发中，构建服务器端逻辑通常较为复杂。开发者往往需要：

在多个代码库之间切换
或依赖第三方服务处理服务器端逻辑

通过将 API 路由直接集成到 React Native 项目中，Expo CLI 和 Expo Router 为开发者提供无缝解决方案：

减少上下文切换
简化开发流程
提升开发效率

二. API 路由语法

API 路由通过在项目 app 目录中新建以 +api.ts 结尾的文件创建。开发者可以导出 HTTP 方法：

GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS

请求方法匹配时，响应函数将被执行。

示例：与 OpenAI 安全交互

// app/generate+api.ts
import { ExpoRequest, ExpoResponse } from 'expo-router/server';

export async function POST(req: ExpoRequest) {
  const { prompt } = await req.json();

  const json = await fetch(
    'https://api.openai.com/v1/engines/text-davinci-003/completions',
    {
      headers: {
        'Content-Type': 'application/json',
        Authorization: Bearer ${process.env.OPENAI_API_KEY ?? ''},
      },
      method: 'POST',
      body: JSON.stringify({
        prompt,
        max_tokens: 100,
      }),
    }
  ).then(res => res.json());

  return ExpoResponse.json(json);
}

开发者可通过 .env 文件安全加载机密信息：

# .env.development
OPENAI_API_KEY=xxxxxx

三. 路由与请求处理

API 路由文件可通过如下 URL 访问：

http://localhost:8081/generate

发起 POST 请求示例：

curl -X POST -H "Content-Type: application/json" \
-d '{"prompt":"Hello, my name is Evan"}' \
http://localhost:8081/generate

在开发环境中，可使用相对 URL：

const json = await fetch('/generate').then(res => res.json());

通过 Expo CLI 的隧道支持，可将服务提供至公网：

npx expo start --tunnel

四. 中间件与运行时环境

引入新包 @expo/server，提供服务器端逻辑所需中间件和运行时环境。

环境变量：服务器路由可访问所有环境变量
运行时功能：支持 Bun 或 Node.js 运行
错误处理与源码映射：服务器端错误格式化与客户端一致

每个 API 路由都会被打包成独立文件，存储在 dist/_expo 目录中。

五. 请求与响应对象

新的请求与响应对象 ExpoRequest 和 ExpoResponse 基于 WinterCG 规范，并兼容 Expo Router。

错误处理示例

// app/blog/[post].ts
import { ExpoRequest, ExpoResponse } from 'expo-router/server';

export async function GET(request: ExpoRequest, { post }: Record<string, any>) {
  if (!post) {
    return new ExpoResponse('No post found', {
      status: 404,
      headers: { 'Content-Type': 'text/plain' },
    });
  }
  return ExpoResponse.json({ post });
}

请求方法未定义时返回 405: Method Not Allowed
请求过程中发生错误时返回 500: Internal Server Error

六. 本地请求支持

支持在本地环境使用相对网络请求，简化跨 Web 和原生平台开发：

fetch('/generate');

开发环境中，Expo 自动解析服务器地址。生产环境中，需要明确指定服务器 URL，可通过 Expo Router 插件在 app.json 配置生产目标。

七. 生产环境支持

API 路由支持动态路由（如 app/[post].tsx），无需额外配置 generateStaticParams
减少构建时工作量，加快导出速度
可部署到大多数网络托管服务
初期支持 Express 和 HTTP 服务器，未来将扩展更多平台

八. 总结

API 路由的引入为 Expo 应用提供了强大的服务器端逻辑支持：

提升开发效率
支持跨平台身份验证
为服务器端渲染和未来 React 服务器组件打下基础

开发者反馈对于完善功能至关重要，欢迎提出建议与意见。

原文链接: https://blog.expo.dev/rfc-api-routes-cce5a3b9f25d