Flutter命令行工具插件backbone_cli的使用

Flutter命令行工具插件backbone_cli的使用

简介

backbone_cli 是一个用于生成 Dart REST API 的命令行工具。如果你在寻找该框架包本身，可以点击 此处。

请注意：此框架仍在早期开发阶段，使用时需自行承担风险。

这个项目大量使用了 mason 包、open_api_forked 包和 shelf 包。如果没有这些库的支持，构建将会非常困难。

开始使用

安装

  1. 确保你的计算机上安装了 Dart。如果你已经安装了 Flutter，很可能也已经安装了 Dart。可以通过运行以下命令检查：

    dart --version

    如果没有安装，可以从 这里 下载。确保版本大于等于 2.12.0；

  2. 通过运行以下命令安装 backbone_cli：

    dart pub global activate backbone_cli

使用

  1. 创建一个新的文件，名为 openapi.yaml。

  2. 使用 Open API 规范定义你的 API，或者复制 示例规范。

  3. 在包含 openapi.yaml 文件的目录下，运行以下命令。这将生成一个新的 Backbone 项目到当前目录。

    backbone generate --new

  4. 当命令完成时，你应该会看到三个新的文件夹。

  5. 随着你更新 openapi.yaml 文件，你可以运行以下命令（不带 --new 参数）来更新 API：

    backbone generate

    更多选项（包括你希望生成的代码所在的目录），可以运行：

    backbone help generate

生成的代码

backbone 生成器会根据你提供的 openapi.yaml 文件自动生成三个 Dart 包：

  1. backend 包。这是运行在服务器上的代码，并提供你的 API。
  2. functions_objects 包。这是后端和前端用来通信的对象。你可以将其视为前端和后端之间的桥梁。
  3. fontend_packages/[API_NAME] 包。这是一个围绕你的 API 的前端包装器，以便从 Flutter 代码中轻松调用。

functions_objects 和 frontend_packages/[API_NAME] 包完全由生成器生成，因此你不需要手动编辑它们。

backend 包有大量的代码由 backbone 自动生成，但你仍然需要编写 API 的功能。

编写你的 API

在初始生成之后，你应该会看到一个文件 backend/lib/[API_NAME].dart。这就是你的 API 端点函数将要放置的地方。

注意：你的函数只需要从这个文件导出，而不一定要直接写在这个文件中。你可以在 backend 包中的任何地方编写你的函数，只要确保它们被从这个文件导出。

你需要编写的函数签名取决于请求是否包含主体以及请求是否有参数。与其记住规则，不如查看 backend/functions.md 文件。它列出了你的 API 需要暴露的所有函数，你可以从那里复制并粘贴到你的源代码中。

编写端点函数

RequestObject

如果请求包含一个主体，你的函数将接收一个名为 [OPERATION-ID]Request 的对象。这是一个简单的 Dart 对象，它将包含通过主体传递给请求的信息。

RequestParameters

如果请求有任何参数（来自路径、查询或头部），你的函数将接收一个名为 [OPERATION-ID]Parameters 的对象。这是一个简单的 Dart 对象，它将包含传递到请求的参数。

ResponseObject

所有请求必须返回一个 200 响应，并且你的函数必须返回一个类型为 [OPERATION-ID]Response 的对象。如果你想让你的函数异步执行，也可以返回该对象的 Future。

RequestContext

每个函数都会接收到请求上下文。它目前包含：

  • rawRequest: 这是一个 shelf.Request 对象，包含了关于请求的所有数据，包括头部等信息。

  • logger: 这是一个 RequestLogger 对象，可以用来记录请求。如果本地运行，它会将日志打印到控制台；如果在 Google Cloud Run 上运行，它会格式化日志以适应 Cloud Logging。你可以这样使用它：

    Future<GetPuppiesResponse> getPuppies(RequestContext context) async {
  context.logger.info('Getting puppies');
}

  • userId: 这是发起请求的用户 ID（如果有）。有关详细信息，请参阅 认证。

  • dependency<T>() 这可以用于在你的后端中缓存依赖项。有关详细信息，请参阅 依赖项缓存。

其他主题

测试你的 API

由于每个端点只是一个函数，你可以很容易地使用 Dart 的 test 包对其进行单元测试。只需模拟请求和请求上下文（我们更喜欢 mocktail 包，但任何方法都可以）。

调试你的 API

由于你的 API 只是 Dart 代码，你可以使用熟悉的 Dart 调试工具进行调试。

实际上，如果你在 Visual Studio Code 中打开 backend 包，在 “Run and Debug” 标签页中，只需单击运行即可开始调试你的 API。

认证

backbone 自动支持通过 JWT 进行认证。要使用它，你需要执行两个步骤：

  1. 在 backend/lib/[API_NAME].dart 文件夹中，实现以下函数：

    Future<String> verifyToken(String token, RequestContext context) async {
  // TODO: 实现 verifyToken
}

    如何实现此函数并不重要，但它应该返回一个包含有效令牌的 userId 的字符串。如果令牌无效，则应抛出 AuthenticationException。

  2. 在你的 openapi.yaml 文件中，向 components 部分添加以下内容：

    securitySchemes:
  [AUTH_SCHEME_NAME]:
    type: http
    scheme: bearer
    bearerFormat: JWT

    然后，在每个操作中添加以下内容：

    security:
  - [AUTH_SCHEME_NAME]: []

  3. 在创建前端对象时，将 authToken 传递给构造函数。

授权

你应该在你编写的函数中授权用户（backbone 不直接支持这一点）。如果用户未授权，函数应抛出 AuthorizationException。

依赖项缓存

你可以使用 RequestContext 对象在你的函数中注入依赖项。

示例

Future<GetPetsResponse> getPets(RequestContext context) async {
  final db = await context.dependency<FirestoreDatabase>(
    () => createAndInitializeDatabase(),
  );
}

你只需要调用 context.dependency<T>(builder)。builder 是一个返回依赖项的函数。关键在于，它只会在尚未构建依赖项时重新构建。例如：

print(await context.dependency<String>(() => 'test1'));
print(await context.dependency<String>(() => 'test2'));
print(await context.dependency<String>(() => 'test3'));

将打印

test1
test1
test1

因为 String 类型的依赖项第一次设置后会被忽略接下来的两次。这对于初始化昂贵的数据库对象非常有用。你可以在第一次需要时初始化它，并在后续需要时重复使用。

如果你想强制 backbone 重置依赖项，只需在函数调用中添加 force: true 选项。

示例

print(await context.dependency<String>(() => 'test1'));
print(await context.dependency<String>(() => 'test2', force: true));
print(await context.dependency<String>(() => 'test3', force: true));

将打印

test1
test2
test3

你还可以通过调用 resetDependencies() 重置 API 中的所有依赖项。这对于测试非常有用，因为你可以在测试中创建一个干净的环境。

注意：虽然我们认为这是解决这个问题的一个很好的方案，但由于这只是 Dart 代码，你可以使用任何你喜欢的模式。

中间件

backbone 完全支持在你的服务器上添加中间件。从顶层的 backend/lib/[API_NAME].dart 文件中，导出一个名为 middlewares 的中间件列表，按你希望它们处理的顺序排列。例如：

final middlewares = <Middleware>[
  fancyLoggingMiddleware(),
  corsMiddleware(),
];

部署你的 API

backbone 生成器会在运行 backbone generate --new 时自动为你创建一个 Dockerfile（在 backend/Dockerfile 中）。你可以通过运行以下命令来构建 Dockerfile：

docker build . -f backend/Dockerfile -t [API_NAME]

更多关于Flutter命令行工具插件backbone_cli的使用的实战教程也可以访问 https://www.itying.com/category-92-b0.html

1 回复

更多关于Flutter命令行工具插件backbone_cli的使用的实战系列教程也可以访问 https://www.itying.com/category-92-b0.html


当然，以下是一个关于如何使用Flutter命令行工具插件 backbone_cli 的示例代码和相关说明。假设 backbone_cli 是一个用于生成Flutter项目骨架的命令行工具插件。

安装 backbone_cli

首先，确保你已经全局安装了 backbone_cli。通常，这样的工具会通过 Dart 的 pub 工具进行安装：

dart pub global activate backbone_cli

使用 backbone_cli 创建新项目

一旦安装完成，你可以使用 backbone_cli 来创建一个新的 Flutter 项目。假设 backbone_cli 提供了一个 create 命令来创建项目，使用方式如下：

backbone_cli create my_new_project

这条命令会在当前目录下创建一个名为 my_new_project 的新 Flutter 项目。

backbone_cli 命令的进一步使用

假设 backbone_cli 还提供了一些其他有用的命令，比如生成页面、模型等。以下是一些假设的命令及其使用方式：

生成页面

backbone_cli generate page my_new_page

这条命令会在项目的 lib 目录下生成一个新的页面文件 my_new_page.dart，内容可能如下：

import 'package:flutter/material.dart';

class MyNewPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('My New Page'),
      ),
      body: Center(
        child: Text('Hello, My New Page!'),
      ),
    );
  }
}

生成模型

backbone_cli generate model user

这条命令会在项目的 lib/models 目录下生成一个新的模型文件 user.dart，内容可能如下：

class User {
  final String name;
  final int age;

  User({required this.name, required this.age});

  factory User.fromJson(Map<String, dynamic> json) {
    return User(
      name: json['name'] as String,
      age: json['age'] as int,
    );
  }

  Map<String, dynamic> toJson() {
    return {
      'name': name,
      'age': age,
    };
  }
}

集成到现有的 Flutter 项目中

假设你已经有一个现有的 Flutter 项目，并希望集成 backbone_cli 生成的内容。你可以按照以下步骤操作：

  1. 导航到项目目录：

    cd path/to/your/existing_flutter_project

  2. 使用 backbone_cli 生成内容：

    backbone_cli generate page new_feature_page

  3. 在 main.dart 或其他路由管理文件中导入并使用新生成的页面：

    import 'package:your_project_name/new_feature_page.dart'; // 假设生成的文件路径正确

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Your Project Name',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MyHomePage(),
      routes: {
        '/new_feature_page': (context) => NewFeaturePage(),
      },
    );
  }
}

注意事项

  • 路径问题：确保 backbone_cli 生成的文件路径正确，如果路径不正确，需要手动调整导入语句。
  • 版本兼容性：检查 backbone_cli 的版本是否与你的 Flutter SDK 版本兼容。
  • 文档：查阅 backbone_cli 的官方文档以获取更多命令和详细用法。

以上示例假设 backbone_cli 的具体命令和生成内容，实际情况可能有所不同。如果 backbone_cli 有具体的文档或 README 文件，请务必参考其官方文档。

回到顶部