Modern.js 项目中的 BFF 函数开发指南

前言

在现代 Web 应用开发中，前后端分离架构已成为主流。Modern.js 提供了一种创新的 BFF（Backend For Frontend）解决方案，让开发者能够更高效地构建全栈应用。本文将详细介绍如何在 Modern.js 项目中使用 BFF 函数功能。

什么是 BFF 函数？

BFF 函数是 Modern.js 提供的一种特殊函数，定义在项目的 api/ 目录下。这些函数可以直接被前端调用，无需手动编写前后端胶水层代码，同时还能保证前后端的类型安全。

启用 BFF 功能

在 Modern.js 项目中启用 BFF 功能非常简单：

1. 确保项目是基于 Modern.js 创建的
2. 在项目配置中确认 BFF 功能已开启
3. 创建 api/ 目录用于存放 BFF 函数

创建第一个 BFF 函数

让我们从一个最简单的 BFF 函数开始：

// api/hello.ts
export const get = async () => 'Hello Modern.js';

这个函数定义了一个 GET 接口，返回简单的字符串。在前端组件中可以这样调用：

// src/App.tsx
import { get as hello } from '@api/hello';

// 在组件中使用
hello().then(response => {
  console.log(response); // 输出: Hello Modern.js
});

Modern.js 会自动将这种函数调用转换为 HTTP 请求，开发者无需关心底层通信细节。

路由系统详解

Modern.js 的 BFF 函数路由基于文件系统实现，遵循约定优于配置的原则。路由系统支持多种高级特性：

1. 默认路由

• api/index.ts → /api/
• api/user/index.ts → /api/user

2. 多级路由

• api/hello.ts → /api/hello
• api/user/list.ts → /api/user/list

3. 动态路由

• api/user/[username]/info.ts → /api/user/:username/info
• api/user/username/[action].ts → /api/user/username/:action

4. 排除规则

以下文件不会被解析为 BFF 函数：

• 以 _ 开头的文件或目录
• 测试文件（如 *.test.ts）
• 类型定义文件（如 *.d.ts）
• node_modules 中的文件

RESTful API 规范

Modern.js 强制遵循 RESTful API 设计规范，这带来了诸多好处：

1. 标准化：接口符合行业标准，易于理解和维护
2. 可扩展性：便于集成到更大的系统中
3. 清晰性：HTTP 方法明确表达操作意图

HTTP 方法支持

Modern.js 支持 9 种 HTTP 方法：

• GET、POST、PUT、DELETE
• CONNECT、TRACE、PATCH
• OPTIONS、HEAD

方法名大小写不敏感，但建议使用小写保持一致性。

函数参数规则

BFF 函数的参数分为两部分：

1. 动态路径参数：来自 URL 的动态部分
2. 请求选项：包含查询参数和请求体

示例：

// api/[sku]/[id]/item.ts
export async function post(
  sku: string,       // 动态路径参数
  id: string,        // 动态路径参数
  { data, query }: RequestOption // 请求选项
) {
  // 业务逻辑
}

类型安全

Modern.js 的 BFF 函数天然支持 TypeScript，提供完整的类型安全：

1. 前后端共享类型定义
2. 自动生成 API 文档
3. 编译时类型检查

最佳实践

1. 保持函数纯净：BFF 函数应专注于数据转换和聚合
2. 合理使用缓存：对频繁访问的数据实现缓存策略
3. 错误处理：统一错误响应格式
4. 日志记录：记录关键操作和错误信息

总结

Modern.js 的 BFF 函数功能为全栈开发提供了极佳的开发体验。通过本文的介绍，你应该已经掌握了：

• 如何创建和调用 BFF 函数
• 路由系统的各种用法
• RESTful API 的设计规范
• 类型安全的最佳实践

这种开发模式显著减少了样板代码，提高了开发效率，同时保证了代码质量和可维护性。无论是小型项目还是大型企业应用，Modern.js 的 BFF 解决方案都能提供强有力的支持。