新建项目

使用 cargo loco 驱动开发

创建你的初始应用：

❯ loco new
✔ ❯ 应用名称？ · myapp
✔ ❯ 你想构建什么？ · 带有客户端渲染的 Saas 应用
✔ ❯ 选择数据库提供商 · Sqlite
✔ ❯ 选择你的后台 Worker 类型 · 异步 (进程内 Tokio 异步任务)

🚂 Loco 应用已成功生成于：
myapp/

- assets: 你已为你的资源服务配置选择了 `clientside`。

下一步，构建你的前端：
  $ cd frontend/
  $ npm install && npm run build

现在 cd 进入你的应用并尝试各种命令：

cargo loco --help

适用于 Rust 的单人框架

用法: demo_app-cli [OPTIONS] <COMMAND>

命令:
  start       启动应用
  db          执行数据库操作
  routes      描述所有应用端点
  middleware  描述所有应用中间件
  task        运行自定义任务
  jobs        管理任务队列
  scheduler   运行调度器
  generate    代码生成，基于预定义的规则集创建一组文件和代码模板
  doctor      验证和诊断配置
  version     显示应用版本
  watch       监视并重启应用
  help        打印此消息或给定子命令的帮助信息

选项:
  -e, --environment <ENVIRONMENT>  指定环境 [默认值: development]
  -h, --help                       打印帮助信息
  -V, --version                    打印版本信息

你现在可以通过 CLI 驱动你的开发：

$ cargo loco generate model posts
$ cargo loco generate controller posts
$ cargo loco db migrate
$ cargo loco start

并且运行测试或使用 Rust 和你已经知道的方式一样：

$ cargo build
$ cargo test

启动你的应用

要运行你的应用，运行：

cargo loco start

后台 Workers

基于你的配置（在 config/ 中），你的 workers 将知道如何运行：

workers:
  # 需要 Redis
  mode: BackgroundQueue

  # 也可以使用：
  # ForegroundBlocking - 非常适合测试
  # BackgroundAsync - 用于同进程任务，使用 tokio async

现在，你可以通过多种方式运行实际进程：

  • rr start --worker - 仅运行一个 worker 并处理后台任务。这非常适合扩展。使用 rr start 运行一个服务应用，然后使用 rr start --worker 运行许多基于进程的 workers，分布在你想要的任何机器上。
  • rr start --server-and-worker - 将在同一个 Unix 进程中同时运行服务和后台 worker 处理器。它使用 Tokio 执行后台任务。这非常适合那些你想要在单个服务器上运行而无需过多开销或资源受限的情况。

获取你的应用版本

因为你的应用是编译的，然后复制到生产环境，Loco 为你提供了两个重要的可操作性信息：

  • 此应用的哪个版本，以及它是从哪个 GIT SHA 构建的？ cargo loco version
  • 此应用是针对哪个 Loco 版本编译的？ cargo loco --version

两个版本字符串都是可解析且稳定的，因此你可以在集成脚本、监控工具等中使用它。

你可以通过覆盖 src/app.rs 文件中的 app_version hook 来塑造你自己的自定义应用版本方案。

使用脚手架生成器

脚手架是一种高效且快速的方法，用于生成应用程序的关键组件。通过利用脚手架，你可以一次性为一个新的资源创建模型、视图和控制器。

查看脚手架命令：

生成 CRUD 脚手架、模型和控制器

用法: demo_app-cli generate scaffold [OPTIONS] <NAME> [FIELDS]...

参数:
  <NAME>       要生成的事物的名称
  [FIELDS]...  模型字段，例如 title:string hits:int

选项:
  -k, --kind <KIND>                要生成的脚手架类型 [可能的值: api, html, htmx]
      --htmx                       使用 HTMX 脚手架
      --html                       使用 HTML 脚手架
      --api                        使用 API 脚手架
  -e, --environment <ENVIRONMENT>  指定环境 [默认值: development]
  -h, --help                       打印帮助信息
  -V, --version                    打印版本信息

你可以从为 Post 资源生成脚手架开始，这将代表一篇博客文章。要完成此操作，请打开你的终端并输入以下命令：

cargo loco generate scaffold posts name:string title:string content:text --api

脚手架生成命令通过添加 --template 标志到脚手架命令来支持 API、HTML 或 HTMX。

脚手架文件布局

脚手架生成器将在你的应用程序中构建多个文件：

文件用途
migration/src/lib.rs包含 Post 迁移。
migration/src/m20240606_102031_posts.rsPosts 迁移。
src/app.rs将 Posts 添加到应用程序路由器。
src/controllers/mod.rs包含 Posts 控制器。
src/controllers/posts.rsPosts 控制器。
tests/requests/posts.rs功能测试。
src/models/mod.rs包含 Posts 模型。
src/models/posts.rsPosts 模型。
src/models/_entities/mod.rs包含 Posts Sea-orm 实体模型。
src/models/_entities/posts.rsSea-orm 实体模型。
src/views/mod.rs包含 Posts 视图。仅适用于 HTML 和 HTMX 模板。
src/views/posts.rsPosts 模板生成器。仅适用于 HTML 和 HTMX 模板。
assets/views/posts/create.html创建 post 模板。仅适用于 HTML 和 HTMX 模板。
assets/views/posts/edit.html编辑 post 模板。仅适用于 HTML 和 HTMX 模板。
assets/views/posts/edit.html编辑 post 模板。仅适用于 HTML 和 HTMX 模板。
assets/views/posts/list.html列表 post 模板。仅适用于 HTML 和 HTMX 模板。
assets/views/posts/show.html显示 post 模板。仅适用于 HTML 和 HTMX 模板。

你的应用配置

默认情况下，loco 将其配置文件存储在 config/ 目录中。它为三个环境提供了预定义的配置：

config/
  development.yaml
  production.yaml
  test.yaml

环境会根据以下内容自动选择：

  • 命令行标志：cargo loco start --environment production，如果未给出，则回退到
  • LOCO_ENV 或 RAILS_ENV 或 NODE_ENV

当没有给出任何内容时，默认值为 development。

除了默认环境之外，Loco 框架还允许支持自定义环境。要添加自定义环境，请创建一个配置文件，其名称与前面示例中使用的环境标识符匹配。

覆盖默认配置路径

要使用自定义配置目录，请将 LOCO_CONFIG_FOLDER 环境变量设置为所需的文件夹路径。这将指示 loco 从指定的目录而不是默认的 config/ 文件夹加载配置文件。

配置中的占位符/变量

可以将值注入到配置文件中。在这个例子中，我们从 NODE_PORT 环境变量中获取端口值：

# config/development.yaml
# 每个配置文件都是一个有效的 Tera 模板
server:
  # 服务器将监听的端口。服务器绑定是 0.0.0.0:{PORT}
  port:  {{ get_env(name="NODE_PORT", default=5150) }}
  # 邮件程序将指向的 UI 主机名或 IP 地址。
  host: http://localhost
  # 开箱即用的中间件配置。要禁用中间件，你可以将 `enable` 字段更改为 `false` 或注释掉 middleware 块

get_env 函数是 Tera 模板引擎的一部分。请参阅 Tera 文档以查看更多你可以使用的内容。

示例

假设你想添加一个 'qa' 环境。在 config 文件夹中创建一个 qa.yaml 文件：

config/
  development.yaml
  production.yaml
  test.yaml
  qa.yaml

要使用 'qa' 环境运行应用程序，请执行以下命令：

LOCO_ENV=qa cargo loco start

设置

配置文件包含用于设置你的 Loco 应用的旋钮。你也可以使用 settings: 部分拥有自己的自定义设置。在 config/development.yaml 中添加 settings: 部分

settings:
  allow_list:
    - google.com
    - apple.com

这些设置将以 serde_json::Value 的形式出现在 ctx.config.settings 中。你可以通过添加结构体来创建强类型设置：

// 将此放在 src/common/settings.rs 中
#[derive(Serialize, Deserialize, Default, Debug)]
pub struct Settings {
    pub allow_list: Option<Vec<String>>,
}

impl Settings {
    pub fn from_json(value: &serde_json::Value) -> Result<Self> {
        Ok(serde_json::from_value(value.clone())?)
    }
}

然后，你可以像这样从任何地方访问设置：

// 在控制器、workers、任务或其他地方，
// 只要你可以访问 AppContext (这里是 `ctx`)

if let Some(settings) = &ctx.config.settings {
    let settings = common::settings::Settings::from_json(settings)?;
    println!("allow list: {:?}", settings.allow_list);
}

Server

以下是 server: 下接口（监听等）参数的详细描述：

  • port: 顾名思义，用于更改端口，主要在负载均衡器等之后。

  • binding: 用于更改 IP 接口 “绑定”到的内容，主要是在你位于像 nginx 这样的负载均衡器之后时，你绑定到本地地址（当 LB 也在那里时）。但是，你也可以绑定到 “world” (0.0.0.0)。你可以通过配置设置 binding: 字段，也可以通过 CLI（使用 -b 标志）——这正是 Rails 正在做的事情。

  • host: - 用于 “可见性” 用例或带外用例。例如，有时你想显示当前服务器主机（在域名等方面），这用于可见性。有时，就像电子邮件的情况一样 —— 你的服务器地址是 “带外的”，这意味着当我打开我的 gmail 帐户并且我有你的电子邮件时 —— 我必须点击看起来像你的外部地址或可见地址（官方域名等），而不是内部 “host” 地址，这可能是错误的做法（想象一下指向 “http://127.0.0.1/account/verify” 的电子邮件链接）

Logger

除了你的 YAML 文件中 logger: 部分的注释字段外，这里还有一些更多上下文：

  • logger.pretty_backtrace - 将显示色彩鲜艳且无噪音的回溯，以获得出色的开发体验。请注意，这会强制将 RUST_BACKTRACE=1 设置到进程的环境中，这会在特定错误时启用（代价高昂的）回溯捕获。在开发环境中启用它，在生产环境中禁用它。当在生产环境中需要时，在命令行中使用 RUST_BACKTRACE=1 临时显示它。

有关所有可用的配置选项，请点击这里

← Axum vs Loco
模型 →
Github 行为准则 许可证 安全