Newshot

Context-Generic Programming (CGP) v0.8.0 - cargo-cgp、新文档与命名空间

AI summary

本次发布主要让 CGP 更易学习和调试:cargo-cgp v0.1.0 会按你写的代码而非宏生成的代码来解释接线错误,例如当 provider 需要你的类型缺少的字段时,cargo cgp check 会指出缺失字段并建议添加。新文档覆盖每个构造、核心概念、与其他语言的比较以及真实项目。命名空间让应用……

Translation(model translation, not the source's own text)

上下文泛型编程(CGP)v0.8.0 已发布!本次发布旨在让 CGP 更易于学习和维护。它引入了 cargo-cgp,一个用于解决 CGP 长期存在的问题的新工具:编译错误描述的是宏生成的代码,而不是你写的代码。cargo-cgp 用你的语言来解释这些错误。例如,当某个 provider 需要你的类型所缺少的字段时,它可以告诉你需要添加哪个字段,而扩展文档则解释了为什么该 provider 需要它。之后,随着你的应用增长,新的命名空间让你可以在一个 wiring 条目中为一整组组件选择 provider。

CGP 是 Rust 的语言扩展,支持在编译期可插拔的 trait 实现。它是稳定版 Rust 上的普通库:应用通过 wiring 选择 provider,wiring 解析为静态调用,你可以一次采用一个组件。概述解释了这一模型。

我先从 cargo-cgp 和新文档讲起,然后通过一个社交媒体应用来讲解命名空间。命名空间的演练是最长的部分,所以如果你愿意,也可以单独阅读工具和文档的新闻。完整文章包括代码在内大约需要 35 分钟,或者直接跳到你需要的小节:

  • 用 cargo-cgp 诊断 wiring
  • 扩展文档与 AI 代理支持
  • 用命名空间对组件 wiring 分组
  • 共享默认实现
  • 其他改进
  • 破坏性变更与迁移

用 cargo-cgp 诊断 wiring​

自 CGP 诞生以来,冗长且令人困惑的编译错误一直是采用它的最大障碍之一。漏掉一个字段或组件绑定,错误信息就可能命名一个生成的 trait,或显示一个被编码为 Rust 类型的字段名。编译器检查的是宏展开后产生的 Rust 代码,因此它的解释可能与我们犯错的那段代码相距甚远。

对新手来说,这可能意味着仅仅为了诊断一个小错误,就要学习高级 Rust trait 和泛型,以及 CGP 的内部机制。你可能理解自己想要写的程序,却仍然不太明白它为什么编译不过。由于困难在于编译器如何报告展开后的代码,仅靠更好的语法无法解决这个问题。

因此我构建了 cargo-cgp v0.1.0,CGP 的新错误工具链,用你写的代码来解释这些错误。cargo cgp check 检查 CGP 代码,并通过所涉及的字段、组件和 provider 来解释缺失的依赖,以根本原因为先导。不过,它尚未重塑所有类别的错误,因此有些错误仍以编译器自己的措辞呈现。当你想深入查看时,cargo cgp expand 会展示宏生成的 Rust 代码。

查找缺失的字段​

让我们在面积计算教程中的一个小错误上试一试。我们有一个面积 provider,将宽度乘以高度,以及一个只提供宽度的 Rectangle。这里,矩形本身就是上下文:它是操作作用的值,它的字段提供 provider 的输入。

将这个库示例保存为使用 cgp = "0.8.0" 的 Cargo 包中的 src/lib.rs:


        use cgp::prelude::*;#[cgp_component(AreaCalculator)]pub trait CanCalculateArea {    fn area(&self) -> f64;}#[cgp_impl(new RectangleArea)]impl AreaCalculator {    fn area(&self, #[implicit] width: f64, #[implicit] height: f64) -> f64 {        width * height    }}#[derive(HasField)]pub struct Rectangle {    pub width: f64,    // missing `height` field}delegate_and_check_components! {    Rectangle {        AreaCalculatorComponent: RectangleArea,    }}
      

该表选择 RectangleArea,其 #[implicit] 参数读取矩形的字段。因为我们使用了 delegate_and_check_components!,编译器会在 wiring 条目处检查这些依赖。运行 cargo cgp check,它会指向我们忘记的字段:

文章标题:Context-Generic Programming (CGP) v0.8.0 - cargo-cgp、新文档与命名空间

正文:


        error[E0277]: [CGP-E001] missing field `height` on `Rectangle`  --> src/lib.rs:23:9   |23 |         AreaCalculatorComponent: RectangleArea,   |         ^^^^^^^^^^^^^^^^^^^^^^^   |   = note: root cause: [CGP-E110] missing field `height` on `Rectangle`           this is required through the dependency chain:             [CGP-E101] consumer trait impl `CanCalculateArea` for context `Rectangle`             └─ [CGP-E102] provider trait impl `AreaCalculator` with context `Rectangle` for provider `RectangleArea`               └─ [CGP-E110] missing field `height` on `Rectangle`   = help: add the field `height: f64` to `Rectangle`
      

帮助信息给出了修改方法,即 height: f64。要弄清 provider 为什么需要它,依赖树会带我们穿过 RectangleArea 回到面积运算。作为对比,普通的 cargo check 通过生成的 trait 和一个嵌套的 Symbol 类型描述了同一个错误:


        error[E0277]: the trait bound `Rectangle: CanUseComponent<AreaCalculatorComponent>` is not satisfied  --> src/lib.rs:23:9   |23 |         AreaCalculatorComponent: RectangleArea,   |         ^^^^^^^^^^^^^^^^^^^^^^^ unsatisfied trait bound   |help: the trait `HasField<Symbol<6, Chars<'h', Chars<'e', Chars<'i', Chars<'g', Chars<_, cgp::macro_prelude::Chars<'t', Nil>>>>>>>>` is not implemented for `Rectangle`      but trait `HasField<Symbol<5, Chars<'w', Chars<'i', Chars<'d', Chars<'t', Chars<_, Nil>>>>>>>` is implemented for it  --> src/lib.rs:17:9   |17 |     pub width: f64,   |         ^^^^^note: required for `RectangleArea` to implement `IsProviderFor<AreaCalculatorComponent, Rectangle>`  --> src/lib.rs:8:1   | 8 | #[cgp_impl(new RectangleArea)]   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^   = note: required for `Rectangle` to implement `CanUseComponent<AreaCalculatorComponent>`note: required by a bound in `__CanUseRectangle`  --> src/lib.rs:21:1   |21 | / delegate_and_check_components! {22 | |     Rectangle {23 | |         AreaCalculatorComponent: RectangleArea,24 | |     }25 | | }   | |_^ required by this bound in `__CanUseRectangle`   = note: this error originates in the attribute macro `cgp_impl` which comes from the expansion of the macro `delegate_and_check_components` (in Nightly builds, run with -Z macro-backtrace for more info)
      

按照该建议,我们补上缺失的字段:


        #[derive(HasField)]pub struct Rectangle {    pub width: f64,    pub height: f64,}
      

接线检查现在通过了,provider 可以读取这两个字段来计算面积。修复这个错误并不需要解码 height 的类型级拼写。

为了生成这一解释,cargo-cgp 封装了一个 nightly 编译器,并使用 Rust 编译器的 API 来检查失败的依赖。它可以利用仅凭打印出的诊断信息很难恢复的信息来追踪它们的链条。正是这种访问能力,使得该工具拥有自己的编译器链接驱动。

试用检查器​

在具备 cargo 和 rustup 的情况下,你可以安装该工具并设置其编译器链接驱动,然后检查你自己的项目。安装需要 Rust 1.96 或更新版本,且该工具目前仅在 Linux 上测试过:


        cargo install --locked cargo-cgpcargo cgp setup# Run this from your CGP project's directory:cargo cgp check
      

cargo cgp setup 会安装该工具固定版本的 nightly,并构建匹配的驱动。该 nightly 只运行 cargo-cgp 的检查,因此你的应用在常规 cargo 构建中仍使用其正常工具链。CGP 本身仍可在 stable Rust 上编译,你完全可以在不安装 cargo-cgp 的情况下使用它。

使用普通的 cargo 来构建、运行和测试应用。cargo-cgp 提供 check 用于诊断,提供 expand 用于阅读宏生成的 Rust 代码,并将 CGP 的类型级构造还原为可读的表示法。安装指南涵盖了设置、更新以及 Nix 替代方案,cargo-cgp v0.1.0 发布说明列出了这个首个版本支持的内容。

扩展文档与 AI agent 支持​

一篇发布文章可能向你展示了一个有趣的功能,却仍然让你不确定如何在自己的程序中使用它。很长一段时间里,CGP 让读者处于这种境地。大多数解释都散落在像本文这样的博客文章中,每篇文章在功能出现时逐一介绍。几乎没有空间去解释每一个构造,或向读者完整说明各个部分如何组合在一起。

CGP 是一个业余项目,抽出时间填补这些空白一直很困难。完全手工撰写一套同等规模的文档,很可能需要我全职工作数月。我不指望在不久的将来能有那样的时间,而等待只会让读者继续面对同样的空白。

AI 和智能体编程的进步使这项工作变得可行。智能体,主要是 Claude Code,在我的指导下撰写了大部分新文档,经历了多轮规划和修订。如果一篇博客文章让你想要更多细节,现在你可以查阅:

  • 参考:查找某个构造可接受的语法、示例和生成的代码。
  • 概念:深入了解诸如 provider 组合、抽象类型和命名空间等概念。
  • 比较:将 CGP 与你从其他编程语言中已经熟悉的方法联系起来,并说明每种比较的局限。
  • 项目:跟随之前博客文章中介绍的 CGP 项目的代码和模式。
  • /cgp 技能:为 AI 助手提供基础,帮助它帮你读写 CGP,如下所述。
  • 知识库:探索为从事 CGP 本身工作的智能体编写的更完整记录,包括其实现和文档。

网站现在包含超过 360 个页面,约 365,000 字的文档正文,不包括代码块和镜像的技能文件。按每印刷页 300 字计算,在代码清单之前大约相当于 1,200 页。

我理解读者为何可能对 AI 撰写的解释持怀疑态度。字数并不能说明它们的实用性,我也不指望一次性的提示就能在这个规模上产出有用的材料。规划、来源核查和反复修订对于我追求的质量至关重要。我鼓励你阅读这些页面,并告诉我哪里解释含糊、不正确,或者读起来像通用的 AI 输出。

文档是如何撰写的​

我指导工作、制定规则,并决定记录哪些内容。过程从知识库开始,智能体在其中记录 CGP 的工作方式,并对照实现、测试和展开快照来核查关于语法和宏展开的说法。这份记录成为网站页面的基础,智能体根据项目的写作指南撰写和修订这些页面。

当某个页面需要更新时,智能体可以从同一份记录继续。这为我节省了时间,因为每次修订都从记录中已有的关于 CGP 的内容开始。知识库概览解释了这份记录如何支撑项目。

我亲自审阅这些页面,但并非所有页面都以同样的深度审阅。我完整阅读每一个解释 CGP 理念或其设计背后决策的页面,包括概念页面和博客文章。各个构造的参考页面遵循其写作指南,我会抽查它们。但两种审阅都不能抓住所有问题。和来源核查一样,它可能遗漏错误,因此知识库仍可能包含错误。我对项目发布的内容负责。

我想在后续的专门文章中进一步探讨这套方法。目前,CGP 的文档是如何撰写的 解释了这一过程及其核查的边界。AI 披露 说明了谁撰写和审阅文档、工具和核心库。

来自 /cgp 技能的可选帮助​

如果你已经在使用 AI 助手,不妨和它一起探索一个小的 CGP 示例。加载 /cgp 技能后,你可以让它解释一个不熟悉的 wiring 条目、追踪某个方法使用的是哪个 provider,或者帮忙排查编译器错误。这样你就能在相关细节出现时深入探索内部细节,并获得适合你 Rust 经验的解释。

该技能为助手提供了一份关于当前 CGP 的精简指南:consumer/provider 模型、wiring、依赖声明,以及使用 cargo-cgp 进行调试。它可以帮助助手调查宏展开,并引导你安装和使用检查器。对于更深层的问题,它可以查阅更完整的知识库记录。

在着手处理你的代码之前,该技能会检查你的项目使用的是哪个 cgp 版本,并在其与技能所描述的版本不一致时告知你。你仍然需要审查并验证助手建议的代码。安装页面说明了如何在你使用的 agent 中安装该技能,而《Using the Knowledge Base with Your Agent》则涵盖了更深入的调查。两者都不是使用 CGP 所必需的。

用命名空间对组件 wiring 进行分组

该版本还引入了命名空间,用于在应用不断增长时对组件进行分组。

当一个应用只有少量组件时,写出它的 delegate_components! 表是很直接的。然而,每当我们把行为拆分到另一个组件时,就会新增一个路由条目。最终,打开这个应用的人不得不在长长的绑定列表中翻找,才能看出哪些条目属于同一组。实现变得更加可复用了,但配置变得更加难以理解。

我尝试过几种方法来应对这一困难。Provider bundle 会收集实现,但应用仍然必须列出它转发给每个 bundle 的组件。更早的 preset 系统也减少了一些重复,但存在一些局限,我将在下文回头讨论。

有了命名空间,我们现在可以给这些组命名,并一起选择它们的实现。我将通过一个社交媒体应用来演示,它的生产配置和测试配置共享一个由 PostgreSQL 支持的核心,但使用不同的内容过滤器。到最后,这一差异将体现在一个 wiring 条目中。

如果你已经维护过一张大型 wiring 表,你可能更愿意直接跳到命名空间语法或迁移指南。否则,让我们从这个小应用开始,看看它的 wiring 是如何增长的。

每个领域从一个 manager 开始

假设我们正在构建一个管理用户和帖子的社交媒体服务。我们需要一个数据库句柄,以及一个用来选择该服务所用实现的地方,因此我们的 context 将代表这个应用。这与之前的 Rectangle 是不同的角色,在那里 context 是被操作的数据。

这些代码片段展示的是 wiring,而不是一个完整的 Web 服务。它们假设了 use cgp::prelude::*;,并省略了领域类型声明和数据库查询体。Web 应用演练遵循同一个示例,其可编译的源代码使用了占位的数据库操作。

我们的服务从用户的一个 manager trait 和帖子的另一个 manager trait 开始。


        #[cgp_component(UserManager)]pub trait CanManageUser {    fn create_user(&self, username: &str, email: &Email) -> Result<User, Error>;    fn get_user(&self, user_id: &UserId) -> Result<User, Error>;    fn update_user_data(&self, user_id: &UserId, user_data: &UserData) -> Result<(), Error>;}#[cgp_component(PostManager)]pub trait CanManagePost {    fn create_post(&self, title: &str, content: &str) -> Result<Post, Error>;    fn get_post(&self, post_id: &PostId) -> Result<Post, Error>;    fn update_post(&self, post_id: &PostId, content: &str) -> Result<(), Error>;    fn delete_post(&self, post_id: &PostId) -> Result<(), Error>;}
      

这些方法描述了服务能做什么。添加 #[cgp_component] 让我们可以把它们的实现与使用它们的应用分开编写:它会生成一个 provider trait(例如 UserManager)和一个 wiring key(例如 UserManagerComponent)。应用将通过该 key 选择 provider。

选择一个 manager provider 就同时选定了它的所有方法。一个 component 可以像普通 trait 一样包含多个方法、关联类型和常量,而把用户操作分组可以让这个初版保持简单。随着服务增长,我们会看到把那些方法放在一起选择在哪些地方变得不便。

对于 PostgreSQL 实现,每个方法都把它需要的数据库句柄声明为隐式参数。这样 provider 就可以与任何提供该依赖的应用配合工作:


        #[cgp_impl(new PostgresUserManager)]impl UserManager {    fn create_user(        &self,        #[implicit] database: &PostgresDb,        username: &str,        email: &Email,    ) -> Result<User, Error> {        // ...    }    fn get_user(        &self,        #[implicit] database: &PostgresDb,        user_id: &UserId,    ) -> Result<User, Error> {        // ...    }    fn update_user_data(        &self,        #[implicit] database: &PostgresDb,        user_id: &UserId,        user_data: &UserData,    ) -> Result<(), Error> {        // ...    }}#[cgp_impl(new PostgresPostManager)]impl PostManager {    fn create_post(        &self,        #[implicit] database: &PostgresDb,        title: &str,        content: &str,    ) -> Result<Post, Error> {        // ...    }    fn get_post(        &self,        #[implicit] database: &PostgresDb,        post_id: &PostId,    ) -> Result<Post, Error> {        // ...    }    fn update_post(        &self,        #[implicit] database: &PostgresDb,        post_id: &PostId,        content: &str,    ) -> Result<(), Error> {        // ...    }    fn delete_post(        &self,        #[implicit] database: &PostgresDb,        post_id: &PostId,    ) -> Result<(), Error> {        // ...    }}
      

任何具有所需 PostgreSQL 数据库字段的 context 都可以复用这些 provider。如果我们想要一个由 SQLite 支持的应用,我们可以针对相同的接口编写 SqliteUserManager 和 SqlitePostManager,并改为选择它们。

对于我们的生产应用,我们提供数据库字段并选择 PostgreSQL managers:


        #[derive(HasField)]pub struct ProductionApp {    pub database: PostgresDb,}delegate_and_check_components! {    ProductionApp {        UserManagerComponent: PostgresUserManager,        PostManagerComponent: PostgresPostManager,    }}
      

两个 manager 共享同一个依赖:即 #[derive(HasField)] 使其可用于它们隐式参数的那个数据库字段。组合的 delegation-and-check 宏会验证 ProductionApp 能够使用所选定的 providers。目前,这两项条目覆盖了所有用户和帖子操作。

随着服务增长添加依赖​

现在假设服务需要拒绝被审查的用户名和垃圾帖子。在插入用户或帖子之前,其 manager 必须咨询一个过滤器。我们可以为每项检查添加一个 component,并用 #[uses] 声明 manager 对其 consumer trait 的依赖:


        #[cgp_component(UsernameCensor)]pub trait CanCensorUsername {    fn username_is_censored(&self, username: &str) -> Probability;}#[cgp_component(SpamMessageDetector)]pub trait CanDetectSpamMessage {    fn message_is_spam(&self, message: &str) -> Probability;}#[cgp_impl(new PostgresUserManager)]#[uses(CanCensorUsername)]impl UserManager {    fn create_user(        &self,        #[implicit] database: &PostgresDb,        username: &str,        email: &Email,    ) -> Result<User, Error> {        if self.username_is_censored(username) > Probability::new(0.8) {            return Err(Error::InvalidUsername);        }        // ...    }    // ...}#[cgp_impl(new PostgresPostManager)]#[uses(CanDetectSpamMessage)]impl PostManager {    fn create_post(        &self,        #[implicit] database: &PostgresDb,        title: &str,        content: &str,    ) -> Result<Post, Error> {        if self.message_is_spam(content) > Probability::new(0.8) {            return Err(Error::InvalidMessage);        }        // ...    }    // ...}
      

每个 manager 在写入数据库之前,都会把其过滤器的分数与拒绝阈值进行比较。#[uses] 属性声明了新的 trait 依赖,而 #[implicit] database 仍然提供数据库句柄。其余 manager 方法在此省略。

在生产环境中,过滤可能涉及 AI 模型或云服务。我们宁愿在测试应用程序其余部分时不必每次都进行这些调用。确定性的字符串匹配过滤器能让测试运行得更快,同时保留相同的 PostgreSQL manager:


        #[derive(HasField)]pub struct ProductionApp {    pub database: PostgresDb,    // ... // AI client credentials}delegate_and_check_components! {    ProductionApp {        UserManagerComponent: PostgresUserManager,        PostManagerComponent: PostgresPostManager,        UsernameCensorComponent: AiUserCensor,        SpamMessageDetectorComponent: AiSpamMessageDetector,    }}#[derive(HasField)]pub struct TestApp {    pub database: PostgresDb,}delegate_and_check_components! {    TestApp {        UserManagerComponent: PostgresUserManager,        PostManagerComponent: PostgresPostManager,        UsernameCensorComponent: DummyUserCensor,        SpamMessageDetectorComponent: DummySpamMessageDetector,    }}
      

两个上下文都提供 database 字段并选择相同的 manager。只有过滤器条目不同,因此测试可以用确定性过滤来运行数据库实现。

随着依赖树增长,接线也变多了。现在每个上下文都有四个条目,所以即使在这个小型服务中,两个上下文合起来已经有八个条目需要保持同步。

独立拆分可复用的操作

将 CanCensorUsername 添加到 user manager 看起来很简单。但这个约束属于整个 PostgresUserManager 实现,所以现在连 get_user 都需要一个带有 censor 的上下文。检索用户从不运行过滤器。这个依赖之所以出现,是因为检索和创建共享同一个 provider。post manager 在垃圾信息检测方面也有同样的问题,而我们每添加一个不相关的依赖,都会让这些 manager 更难维护和测试。

随着我们添加操作,领域边界也变得不那么明显。get_user_profile_picture 可能适合放在 user manager 中,但它可能需要一组完全不同的依赖。get_user_posts 同时涉及用户和帖子。以实体命名 manager 并不能确定哪些操作适合放在一起。

还有一个理由要保持调用方接口的狭窄。删除用户是破坏性操作,我们可能不希望每一段处理用户的代码都能执行删除。然而,如果我们将 delete_user 添加到 manager 中,即使是只检索用户的通用代码也会获得删除权限。给检索一个自己的 trait,可以让那段代码只请求它需要的操作,不多不少。

文章标题:Context-Generic Programming (CGP) v0.8.0 - cargo-cgp、新文档与命名空间

正文: 这指向了一个简单但强大的模式,CGP 让它变得实用:把每个管理器拆分成细粒度的 trait,每个 trait 只承载一个操作或几个紧密相关的操作。这样,每个 provider 只需声明它用到的依赖。对于用户操作,这给了我们:


        #[cgp_component(UserCreator)]pub trait CanCreateUser {    fn create_user(&self, username: &str, email: &Email) -> Result<User, Error>;}#[cgp_component(UserGetter)]pub trait CanGetUser {    fn get_user(&self, user_id: &UserId) -> Result<User, Error>;}#[cgp_component(UserUpdater)]pub trait CanUpdateUser {    fn update_user_data(&self, user_id: &UserId, user_data: &UserData) -> Result<(), Error>;}
      

创建用户的 provider 需要 censor,而 getter 只需要数据库:


        #[cgp_impl(new CreateUserWithPostgres)]#[uses(CanCensorUsername)]impl UserCreator {    fn create_user(        &self,        #[implicit] database: &PostgresDb,        username: &str,        email: &Email,    ) -> Result<User, Error> {        if self.username_is_censored(username) > Probability::new(0.8) {            return Err(Error::InvalidUsername);        }        // ...    }}#[cgp_impl(new GetUserWithPostgres)]impl UserGetter {    fn get_user(&self, #[implicit] database: &PostgresDb, user_id: &UserId) -> Result<User, Error> {        // ...    }}
      

GetUserWithPostgres 可以只依赖数据库使用,而 CreateUserWithPostgres 保留了它的 censor 依赖。以 CanGetUser 为约束的调用方可以获取用户,而不依赖创建或删除。同样的拆分给了我们独立的创建后、获取、更新和删除组件。

将过滤与数据库访问分离​

拆分组件解决了 getter 的问题,但 CreateUserWithPostgres 仍然做两件事:先检查用户名,再把用户插入 PostgreSQL。只有插入操作与数据库有关。如果我们为 SQLite 添加一个 provider,它就得重复同样的检查。由于创建现在有了自己的组件,我们可以把检查移到一个 wrapper 中,并将它应用到我们选定的任意用户创建 provider 上:


        #[cgp_impl(new FilterCensoredUsername<InnerCreator>)]#[uses(CanCensorUsername)]#[use_provider(InnerCreator: UserCreator)]impl<InnerCreator> UserCreator {    fn create_user(&self, username: &str, email: &Email) -> Result<User, Error> {        if self.username_is_censored(username) > Probability::new(0.8) {            return Err(Error::InvalidUsername);        }        InnerCreator::create_user(self, username, email)    }}#[cgp_impl(new CreateUserWithPostgres)]impl UserCreator {    fn create_user(        &self,        #[implicit] database: &PostgresDb,        username: &str,        email: &Email,    ) -> Result<User, Error> {        // ...    }}
      

该 wrapper 会拒绝被审查的名字,然后把允许的请求交给 InnerCreator::create_user。它的 #[use_provider] 属性要求内层 provider 为同一个 context 支持用户创建。由于它把另一个 provider 作为参数,我们称 FilterCensoredUsername 为高阶 provider。

CreateUserWithPostgres 现在可以专注于构造 SQL 插入查询。在装配应用时,我们可以直接选择它,或者用 FilterCensoredUsername<CreateUserWithPostgres> 添加过滤。一个本地优先的应用也可以选择 FilterCensoredUsername<CreateUserWithSqlite>,并复用同一个过滤器。更换数据库不需要复制用户名检查。

FilterSpamMessage<InnerCreator> 对帖子创建应用了同样的分离。它使用 CanDetectSpamMessage 来拒绝垃圾内容,然后把允许的帖子转发给它的内层 PostCreator。因此,装配时可以独立于数据库 provider 的实现来选择 FilterSpamMessage<CreatePostWithPostgres>。

权衡分离的代价​

文章标题:Context-Generic Programming (CGP) v0.8.0 - cargo-cgp、新文档与命名空间

正文: 依赖被隔离、过滤器可复用之后,各个 provider 使用起来更简单了。然而,生产环境的装配现在必须选择七个 CRUD 操作和两个过滤器:


        delegate_components! {    ProductionApp {        UserCreatorComponent:            FilterCensoredUsername<CreateUserWithPostgres>,        UserGetterComponent:            GetUserWithPostgres,        UserUpdaterComponent:            UpdateUserWithPostgres,        PostCreatorComponent:            FilterSpamMessage<CreatePostWithPostgres>,        PostGetterComponent:            GetPostWithPostgres,        PostUpdaterComponent:            UpdatePostWithPostgres,        PostDeleterComponent:            DeletePostWithPostgres,        UsernameCensorComponent:            AiUserCensor,        SpamMessageDetectorComponent:            AiSpamMessageDetector,    }}
      

拆分 manager 之后,我们的装配表从四条记录变成了九条,而真实应用可能有几十甚至几百条。想象一下第一次打开这张表的情形。要了解应用如何处理用户,你得从列表里挑出用户相关的绑定,而其余内容读起来都像是噪音,掩盖了 ProductionApp 真正做的事。于是应用看起来比实际复杂得多,这也是冗长的装配表让 CGP 更难被采用的原因之一。

这张表一次性展示了太多内容。如果我们把它拆成更小的组,读者就能一次只看一部分装配,因此我们先从把用户绑定收集到它们自己的 provider bundle 开始:


        delegate_components! {    new PostgresUserComponents {        UserCreatorComponent:            FilterCensoredUsername<CreateUserWithPostgres>,        UserGetterComponent:            GetUserWithPostgres,        UserUpdaterComponent:            UpdateUserWithPostgres,    }}
      

借助 new PostgresUserComponents,我们声明了一个聚合 provider:它的表把每个操作委托给另一个 provider。读者可以单独查看用户相关的装配,而不必同时看到 post 操作和过滤器。我们可以用同样的方式,把那些内容收集到 PostgresPostComponents 和 AiContentFilterComponents 中。

回到应用中,我们用数组键把组件转发到各自的 bundle:


        delegate_components! {    ProductionApp {        [            UserCreatorComponent,            UserGetterComponent,            UserUpdaterComponent,        ]:            PostgresUserComponents,        [            PostCreatorComponent,            PostGetterComponent,            PostUpdaterComponent,            PostDeleterComponent,        ]:            PostgresPostComponents,        [            UsernameCensorComponent,            SpamMessageDetectorComponent,        ]:            AiContentFilterComponents,    }}
      

这些 bundle 让每一组都更易读,但并没有缩短应用需要列出的内容。应用的装配表仍然要写出全部九个组件,只是现在分散在三个列表里,而每个列表都重复了其 bundle 已经包含的键。因此新增一个用户操作需要改两处:一处在用户 bundle 中,另一处在每一个委托给它的应用中。在大型代码库里,第二处修改可能意味着很多地方。我们更希望告诉应用:「所有用户组件」都用 PostgresUserComponents,但这一组并没有我们可以装配的名字。

为什么早期的分组方法不够用​

理想情况下,配置应该写成这样,每个组对应一个键:


        delegate_components! {    ProductionApp {        ???: // all user components            PostgresUserComponents,        ???: // all post components            PostgresPostComponents,        ???: // all content filter components            AiContentFilterComponents,    }}
      

文章标题:Context-Generic Programming (CGP) v0.8.0 - cargo-cgp、新文档与命名空间

正文: ??? 键才是难点所在。表格中的每一项都会变成一个键的 trait 实现,因此 UserCreatorComponent: … 会为应用提供一个实现,用于应答用户创建相关的查找。一个代表所有用户组件的键,需要为该组中的每个组件各生成一个实现,而 Rust 的 trait 系统无法这样展开单个条目。因此 CGP 需要另一种方式来识别一个组:要么使用自己的查找规则,要么使用一个将组展开为其各个键的宏。命名空间采用了第一条路线,但宏路线值得先看一看。

一种可能是提供一个辅助宏,为每个组给出键的列表。这样我们就能写出一个假想的表格,如下所示:


        delegate_components! {    ProductionApp {        all_user_components!():            PostgresUserComponents,        all_post_components!():            PostgresPostComponents,        all_content_filter_components!():            AiContentFilterComponents,    }}
      

在这里,all_user_components!() 会展开为 [UserCreatorComponent, UserGetterComponent, UserUpdaterComponent],posts 和 filters 也有对应的列表。与上面的 ??? 键一样,这些辅助宏是伪代码,而非受支持的语法。

不幸的是,这撞上了 Rust 展开宏的顺序问题。Rust 是惰性展开的,由外向内,因此 delegate_components! 会先运行,并把 all_user_components!() 作为字面 token 接收。此时辅助宏尚未展开,组件列表还不存在。表格需要急切展开,即宏在读取输入之前先展开输入中的宏,而稳定的 Rust 不提供任何让宏做到这一点的方法。即便可以,CGP 仍然必须生成 all_user_components! 这样的辅助宏并导出它们,以便其名称和导入在其他 crate 中继续可用,而 Rust 的宏系统对此支持有限。

我早先的 preset 系统尝试解决同一个问题,但它只支持类似单继承的层级结构。一个上下文可以继承一个 preset,例如 user preset,而 Rust 的一致性限制随后会阻止它再继承一个独立的 post preset。我也尝试过通过宏组合多个 preset,但急切开宏展开的缺失,加上导入和别名在宏输出中的解析方式,使得那种方法用起来很繁琐。

这些尝试帮助厘清了我想从这个特性中得到什么:应用应当能够命名一个组并选择其实现包,而不必逐一列举每个键。在 v0.8.0 中,命名空间通过 trait 解析和路径来表达这一选择。现有的 preset 用户可以在迁移部分找到转换方法。

为组件组赋予路径​

现在我们可以用路径来替换 ??? 键,这些路径分别命名 user、post 和 content-filter 组。注册组件前缀后,我们的应用表格变为:


        delegate_components! {    ProductionApp {        namespace DefaultNamespace;        @app.core.user: PostgresUserComponents,        @app.core.post: PostgresPostComponents,        @app.extra.content_filter: AiContentFilterComponents,    }}
      

namespace DefaultNamespace; 语句将这些路径与我们的组件连接起来。每个组件都在内置的 DefaultNamespace 中注册一条路由,正如我们稍后将用 #[prefix] 所做的那样,而该语句告诉表格沿着这些路由走。命名空间是选择性启用的,因此没有这条语句时,表格会忽略已注册的路由。例如,对 UserCreatorComponent 的查找会沿着一条以 @app.core.user 开头的路由,从而到达选择 PostgresUserComponents 的条目。因此,向用户组中添加另一个用户操作不会改动这个表格。各个绑定仍然存在于实现包中,而应用只选择它使用哪些组。稍后,我们还会定义自己的命名空间。

文章标题:Context-Generic Programming (CGP) v0.8.0 - cargo-cgp、新文档与命名空间

正文: 为实现这一点,我们使用 #[prefix] 为每个组件加上前缀。对于 CanCreateUser,我们在内置的 DefaultNamespace 中注册 @app.core.user:


        #[cgp_component(UserCreator)]#[prefix(@app.core.user in DefaultNamespace)]pub trait CanCreateUser {    fn create_user(&self, username: &str, email: &Email) -> Result<User, Error>;}
      

CGP 会把组件标记追加到这个前缀之后。一旦某个 context 加入该命名空间,对 UserCreatorComponent 的查找就会沿着这条路由走到 @app.core.user.UserCreatorComponent。

getter 和 updater 也属于该分组,因此我们在同一个前缀下注册它们。对于 getter,这意味着:


        #[cgp_component(UserGetter)]#[prefix(@app.core.user in DefaultNamespace)]pub trait CanGetUser {    fn get_user(&self, user_id: &UserId) -> Result<User, Error>;}
      

post 相关操作拥有自己的 @app.core.post 前缀:


        #[cgp_component(PostCreator)]#[prefix(@app.core.post in DefaultNamespace)]pub trait CanCreatePost {    fn create_post(&self, title: &str, content: &str) -> Result<Post, Error>;}
      

最后,filter 组件注册在 @app.extra.content_filter 下,同样位于 DefaultNamespace 中。这些注册只命名分组,并不为它们选择任何 provider。这一选择仍留给每个应用,因此生产环境、测试环境和一个 SQLite 变体可以共享相同的路由,同时仍然选择不同的 bundle。

按层级组织组路径​

生产环境和测试环境都使用 PostgreSQL 的 user 与 post 操作。与其在每个应用中分别选择这些 bundle,我们可以把它们收集到共同的父路径 @app.core 下。这些路径是分层的:@app.core.user 位于 @app.core 之下,而 @app.core 又位于 @app 之下。因此,一个中间 bundle 可以汇集核心操作,另一个则汇集 extras:


        delegate_components! {    new PostgresCoreComponents {        namespace DefaultNamespace;        @app.core.user: PostgresUserComponents,        @app.core.post: PostgresPostComponents,        // other core components    }}delegate_components! {    new ProductionExtraComponents {        namespace DefaultNamespace;        @app.extra.content_filter: AiContentFilterComponents,        // other extra components    }}
      

请注意,这些中间 bundle 也加入了 DefaultNamespace。当查找到达某个 bundle 时,它收到的是裸组件键,而 namespace 语句会把该键重定向到 bundle 自身表中的路径。我们之前那些叶子 bundle 已经使用裸组件名,因此不需要该语句。

现在生产配置选择两个组:


        delegate_components! {    ProductionApp {        namespace DefaultNamespace;        @app.core: PostgresCoreComponents,        @app.extra: ProductionExtraComponents,    }}
      

现在,@app.core 的一条条目就能覆盖两个核心组。由于路径是分层的,它会匹配该前缀下的每一条路由,因此 user 和 post 的查找都能到达它,我们以后新增的核心组也一样。再以 UserCreatorComponent 为例。它的路由 @app.core.user.UserCreatorComponent 以 @app.core 开头,因此 ProductionApp 会把查找转发给 PostgresCoreComponents。在该 bundle 内部,namespace 语句会对组件进行第二次路由,将其带到 @app.core.user 条目,再到达 PostgresUserComponents。

对于测试,核心保持不变。只有 extras 条目发生变化,选择 DummyExtraComponents 以获得确定性的过滤:


        delegate_components! {    TestApp {        namespace DefaultNamespace;        @app.core: PostgresCoreComponents,        @app.extra: DummyExtraComponents,    }}
      

对于本地配置,我们可以做另一种选择:保留生产环境的 filter,并选择由 SQLite 支撑的核心:


        delegate_components! {    LocalApp {        namespace DefaultNamespace;        @app.core: SqliteCoreComponents,        @app.extra: ProductionExtraComponents,    }}
      

文章标题:Context-Generic Programming (CGP) v0.8.0 - cargo-cgp、新文档与命名空间

正文: 在每种情况下,都有一个条目告诉我们该配置与生产环境有何不同。TestApp 修改的是 extras,而 LocalApp 修改的是 core。若使用扁平表,我们就必须比较各个组件的条目,而这些条目可能以不同的顺序书写,才能得出相同的结论。现在,我们可以直接从 wiring 中读出这些决策。

选定的 provider 仍然需要它们的依赖项。每个 context 都必须提供所需的字段和其他 trait,而假想的 SQLite core 则需要其对应的数据库句柄。

检查已完成的配置

这些 provider 能否协同工作?delegate_components! 块可能在 Rust 检查 provider 的依赖项之前就编译通过。我们可以用 check_components! 让 Rust 现在检查它们,在具体 application 上指明我们需要的组件。


        check_components! {    ProductionApp {        UserCreatorComponent,        UserGetterComponent,        UserUpdaterComponent,        PostCreatorComponent,        PostGetterComponent,        PostUpdaterComponent,        PostDeleterComponent,        UsernameCensorComponent,        SpamMessageDetectorComponent,    }}
      

对 TestApp 和任何本地变体应用同样的九组件检查。更早的阶段需要与各自组件匹配的检查:例如,在拆分 manager 之前,检查 UserManagerComponent 和 PostManagerComponent。

该检查会列出各个单独的操作,尽管 wiring 现在按组路由它们。组条目只说明查找去向,因此检查确认我们所依赖的每个操作确实能被解析。在真实的 application context 上运行它,该 context 提供数据库字段和其他依赖项。聚合 provider 只是实现的捆绑包,因此把捆绑包当作 application 来检查,会要求它提供只有 context 才能提供的依赖项。

命名空间文档解释了查找模型,delegate_components! 参考文档涵盖了路径语法。

共享默认实现

到目前为止,我们围绕可能想要更改的选择来组织 wiring:PostgreSQL 或 SQLite,生产或测试过滤器。捆绑包非常适合这种安排。例如,我们可以添加一个 PostgresWithLoggingCoreComponents 变体,并在同一位置选择由日志支持的核心。

但一个从 PostgreSQL 起步的 application 可能还没有理由定义可互换的数据库捆绑包。在项目早期,开发者通常更倾向于每个功能一个实现,并有意将其与接口绑定,因为这能让 application 易于推理。如果多个 context 应始终使用相同的 user 和 post 实现,让每个 context 选择这些捆绑包会重复一个永不改变的选择。我们可以改为在命名空间中记录这些选择一次,只把变化的部分留给每个 context。这些就是默认实现。

我认为默认实现是逐步采用 CGP 的一种方式。对于只有每个操作一个实现的单 crate application,普通 trait 可能已经足够。如果该 application 后来需要更多模块化,它可以将代码移入 CGP 组件,并将其初始 provider 选择记录为默认值。当存在可交换的有用分组时,捆绑包可以随后跟进。

让我们保留已在 DefaultNamespace 中注册的路由,并使用新的 cgp_namespace! 宏定义一个继承它们的配置命名空间:


        cgp_namespace! {    new DefaultAppComponents: DefaultNamespace}
      

DefaultAppComponents 从其父级获得前缀和任何默认绑定。我们可以在此添加 application 特定的选择,而不改变其他命名空间的选择。加入此配置命名空间的每个 context 都将共享这些选择。

对于简单的 provider,我们可以将其绑定放在其实现旁边。为我们之前的 GetUserWithPostgres 定义添加 #[default_impl]:

文章标题:Context-Generic Programming (CGP) v0.8.0 - cargo-cgp、新文档与命名空间

正文:


        #[cgp_impl(new GetUserWithPostgres)]#[default_impl(@app.core.user.UserGetterComponent in DefaultAppComponents)]impl UserGetter {    fn get_user(&self, #[implicit] database: &PostgresDb, user_id: &UserId) -> Result<User, Error> {        // ... query the database    }}
      

现在这个实现声明了 DefaultAppComponents 在 @app.core.user.UserGetterComponent 处使用它。如果我们更希望把所有绑定集中在一处,也可以在命名空间主体中写出同样的选择:


        cgp_namespace! {    DefaultAppComponents {        @app.core.user.UserGetterComponent: GetUserWithPostgres,    }}
      

这两种方式都是注册同一个绑定的替代写法,所以同时写出两者会产生冲突。命名空间主体看起来像 delegate_components! 表,但其中的选择适用于加入该命名空间的每个上下文。我们用完整路径绑定 provider,因为裸键已经被占用。从 DefaultNamespace 继承来的路由使用 UserGetterComponent 把查找转发给 @app.core.user.UserGetterComponent,所以再为裸键添加一个条目会与它冲突。

这些默认值是固定的选择。一旦命名空间绑定了某个 provider,加入的上下文或继承的命名空间就无法覆盖它,即使使用更具体的条目也不行。上下文也无法只禁用某一个默认值而保留该命名空间的其余部分。因此,应当在命名空间留开放的路径上做那些需要随上下文变化的选择,正如我们下面要对过滤器所做的那样。

关于我们在哪里写注册,还有一个约束。使用带前缀的路径时,绑定必须位于拥有该命名空间的 crate 中,这里是 DefaultAppComponents。该路径会展开为 CGP 的 PathCons 类型,而拥有嵌套在该类型内部的组件标记并不满足 Rust 的孤儿规则。无前缀的本地组件标记有不同的所有权规则,参见 #[default_impl] 的参考文档。

在命名空间主体中绑定组合 provider​

FilterCensoredUsername 对其内部 provider 是泛型的。在这个配置中,我们想要同时选择包装器和它的 PostgreSQL 实现。我们可以直接在命名空间主体中组装这个完整的 provider 选择:


        cgp_namespace! {    DefaultAppComponents {        @app.core.user.UserCreatorComponent:            FilterCensoredUsername<CreateUserWithPostgres>,    }}
      

在我们用同样的方式绑定其余 user 和 post provider 之后,应用只需要选择它的过滤器。对于这个示例,我们的生产环境装配就变成了:


        delegate_components! {    ProductionApp {        namespace DefaultAppComponents;        @app.extra.content_filter: AiContentFilterComponents,    }}
      

每个加入 DefaultAppComponents 的上下文都会从它那里获得 user 和 post provider。我们把过滤器路径留开放,这样测试上下文就可以在那里改用 DummyContentFilterComponents。

选择共享多少装配​

我们把前缀留在 DefaultNamespace、把 provider 选择留在 DefaultAppComponents 中是有原因的。另一个配置,例如 SQLite 的配置,就可以继承相同的路由,而不会同时继承它无法覆盖的 PostgreSQL 选择。因此,路由属于基础命名空间,固定选择属于继承它的配置命名空间。

如果以后我们需要替换其中某个固定默认值,就选择一个让其目标保持开放的命名空间。我们可以回到基础的 DefaultNamespace 并显式提供所需的绑定,就像前面的 bundle 示例那样。

当应用还位于一个 crate 中时,#[default_impl] 可以方便地让每个绑定与它的实现放在一起。一旦 provider 移到各自的 crate 中,该属性就会位于一个并不拥有该命名空间的 crate 中,而上面的所有权规则禁止这样做。因此,我们改为把绑定移入配置命名空间的主体,由该命名空间所在的 crate 在那里组装 provider。

可以从直接连线开始,通过 defaults 共享固定选择,并随着应用需要引入可互换的 bundles。我会选择让当前决策最容易被看清的那种安排,而不是为了预期未来的增长而构建完整的层级结构。

其他改进

命名空间是最大的变化,但若干较小的新增功能也让 CGP 更易于编写、阅读,并能在更多类型的 crate 中使用。你可以在不遵循上述完整应用重构的情况下使用这些功能:

  • 使用 open 为每个类型选择 provider。如果一个泛型组件需要为矩形使用一个 provider,为圆形使用另一个 provider,你可以将这些选择直接放在 context 的表中。你不需要声明命名空间或嵌套的 UseDelegate 表。delegate_components! 参考文档展示了语法。
  • 使用 for 组装独立的表。后端和 API 表面可以各自拥有自己的 defaults 表。你可以将另一个命名空间表中的条目带到 context 中的某个路径上,从而保持这些关注点独立定义。参见 namespace 语句。
  • 将实现细节排除在 trait 参数之外。有时 #[cgp_fn] 函数体需要一个泛型类型,仅仅是因为它要读取该类型的某个字段。使用 #[impl_generics],实现可以从隐式字段推断出该类型,而无需向生成的 trait 添加参数。
  • 将数据形状写成声明。当字段列表看起来像它所描述的结构体或枚举时,就更容易识别。Struct! 和 Enum! 提供了这种记法,cargo-cgp 在显示形状时也会使用它。
  • 直接使用无字段变体。如果一个枚举包含诸如 Closed 这样的状态,你现在可以使用 extensible-variant derives 而无需给它一个占位 payload。这些 derives 接受 Closed、Closed() 和 Closed {},将 payload 表示为 Nil。使用可变提取器的 no_std crate 必须将 Box 引入作用域。
  • 在没有标准库的情况下构建。使用其默认特性时,cgp 既不需要 std 也不需要分配器,因此它适用于既没有两者之一的目标平台上的 no_std crate。将错误格式化为 String 的两个错误 provider——DebugError 和 DisplayError——需要新的 alloc 特性。
  • 借用任何字符串字段。#[implicit] name: &str 参数现在可以读取任何类型实现了 AsRef<str> 的字段,例如 String、Box<str> 或 Cow<'static, str>,而在 v0.7.0 中要求使用 String。Option<&str> 参数可以读取上述任何类型的 Option。
  • 为宏生成的内容提供文档。每个声明公共项的宏在你未编写文档时都会给它一行简短的文档,因此 crate 可以开启 #![warn(missing_docs)] 而不会让 lint 标记组件标记或 provider 结构体。provider trait 的文档还会指明其组件键,因此在编辑器中悬停该 trait 时会显示要导入的键。
  • 在缺少组件键时获得帮助。编写为 impl Greeter 的 provider 需要将键 GreeterComponent 引入作用域,因此另一个模块中的 provider 会连同 trait 一起导入该键。如果你忘记了,cargo cgp check 会报告 CGP-E041 并提供添加 use 行的修复。你也可以通过路径命名 trait 来跳过导入,如 #[cgp_impl] 参考文档所解释的那样。

关于较小的变化,例如 handler 宏更清晰的错误信息以及此版本解除的限制,请参阅 v0.8.0 发行说明。

破坏性变更与迁移

从 v0.7.0 升级需要修改源代码。最大的变化是移除了 presets,此版本用命名空间取而代之,大多数应用还需要为以前来自 prelude 的项添加显式导入。v0.8.0 发行说明按顺序列出了每一项变更及升级步骤。

有两个使用 CGP 构建的项目同时迁移到 v0.8.0。cgp-serde 0.3.0 现在可以序列化和反序列化枚举,Hypershell 0.2.0 从命名空间而非 presets 组装其语言。如果你的代码基于其中任何一个构建,cgp-serde v0.3.0 和 Hypershell v0.2.0 的发行说明给出了升级步骤。

用命名空间配置取代预设

v0.8.0 移除了先前描述的预设系统。其共享的 provider 选择可以变成命名空间绑定,而需要保持可互换的组可以变成通过路径选择的具体聚合 provider。

以下 v0.7.0 示例定义了一个预设,并将其继承到一个上下文中。这是旧语法,无法在 v0.8.0 中编译:


        cgp_preset! {    PostgresUserComponents {        UserCreatorComponent:            FilterCensoredUsername<CreateUserWithPostgres>,        UserGetterComponent: GetUserWithPostgres,        UserUpdaterComponent: UpdateUserWithPostgres,    }}#[cgp_inherit(PostgresUserComponents)]pub struct ProductionApp {    pub database: PostgresDb,}delegate_components! {    ProductionApp {        // The inherited preset supplies the user-component entries.        // Other component bindings go here.    }}
      

配置命名空间可以保留预设固定的 user-provider 选择。在 DefaultNamespace 下使用前面所示的 #[prefix(... in DefaultNamespace)] 属性,将用户组件注册到 @app.core.user 下。然后用此命名空间替换预设:


        cgp_namespace! {    new PostgresAppNamespace: DefaultNamespace {        @app.core.user.UserCreatorComponent:            FilterCensoredUsername<CreateUserWithPostgres>,        @app.core.user.UserGetterComponent: GetUserWithPostgres,        @app.core.user.UserUpdaterComponent: UpdateUserWithPostgres,    }}
      

迁移后的上下文还必须提供其创建包装器所需的 censor。在 DefaultNamespace 下将 UsernameCensor 注册到 @app.extra.content_filter 下。注册用户组件和过滤器后,用上下文上的显式委托替换继承属性:


        #[derive(HasField)]pub struct ProductionApp {    pub database: PostgresDb,}delegate_components! {    ProductionApp {        namespace PostgresAppNamespace;        @app.extra.content_filter.UsernameCensorComponent: AiUserCensor,    }}check_components! {    ProductionApp {        UserCreatorComponent,        UserGetterComponent,        UserUpdaterComponent,        UsernameCensorComponent,    }}
      

上面的示例特意只检查了迁移后的用户组及其过滤器。请添加 post 操作以及你的应用程序使用的任何其他依赖项。

聚合 provider 使 user-provider 组保持可互换。如果配置需要这种变化,请使用 delegate_components! { new PostgresUserComponents { ... } } 保留 PostgresUserComponents,并用 @app.core.user: PostgresUserComponents 选择它,如同主演练中那样。根据应该变化的内容,在此可配置捆绑安排与上面的固定命名空间绑定之间进行选择。

已移除的预设构造及其替代方案如下:

已移除的构造应使用什么
cgp_preset!用于共享固定选择的配置命名空间,或用于可选择组的聚合 provider。
#[cgp_inherit]delegate_components! 内的 namespace ...; 语句和显式路径条目。
#[wrap_provider]显式聚合 provider 和委托条目。
#[cgp::re_export_imports]用于命名空间或委托表中类型的普通 Rust 导入。
IsPreset移除预设标记上的约束。查询命名空间的泛型代码使用该命名空间生成的查找 trait。
replace_with!无。预设生成的宏通过它展开,因此移除你自己编写的任何调用。

导入 prelude 不再导出的内容

文章标题:Context-Generic Programming (CGP) v0.8.0 - cargo-cgp、新文档与命名空间

正文: cgp::prelude 现在只导出 CGP 代码通常会写的名称:宏、derive、PhantomData,以及少数 trait 和 provider,例如 HasErrorType、CanRaiseError、UseType 和 DefaultNamespace。宏生成的代码通过单独的 cgp::macro_prelude 访问 CGP 的条目,因此 prelude 不再需要携带这些条目。如果你的代码通过 glob 导入引用了某个被移除的条目,编译器会报告找不到它,此时你应从其所属模块中导入:


        use cgp::core::component::DelegateComponent;use cgp::core::field::traits::HasField;use cgp::extra::handler::{Computer, ComputerComponent};
      

被移除的名称来自以下模块:

  • 接线 trait,例如 DelegateComponent 和 IsProviderFor:cgp::core::component。
  • 字段访问 trait 和类型级类型,例如 Cons、Nil 和 Index:cgp::core::field 下的模块。
  • HasType 和 TypeProvider:cgp::core::types。
  • handler 家族,及其 trait、key 和 provider:cgp::extra::handler。

derive 不需要导入其 trait,因此 #[derive(HasField)] 仍可通过 prelude 工作,而 HasField 约束或 .get_field() 调用则需要导入。handler trait(例如 Computer)的 provider 需要在其 trait 旁边导入其 key ComputerComponent,因为 provider 的头部会命名该 key,如“其他改进”中所述。

因此,原始编译器输出的内容会略有变化。v0.7.0 打印 cgp::prelude::Chars 这样的类型,而现在编译器可以打印 cgp::macro_prelude::Chars,如上面的 cargo check 对比所示。

类型级类型也失去了它们的希腊字母名称。v0.7.0 将它们声明为 π、ε、σ、θ、ζ、ψ、δ 和 ω,并以 Cons、Nil、Either、Void、Chars、Symbol、Index 和 Field 作为别名,prelude 导出了两种拼写。现在只保留英文名称,因此写了希腊名称的代码需改用英文名称,并从 cgp::core::field::types 导入。原始编译器输出也随之变化,在 v0.7.0 打印 π<…> 和 ζ<…> 的地方,现在打印 Cons<…> 和 Chars<…>。

为格式化错误 provider 开启 alloc​

cgp 的默认 feature 现在为空,因此该库在没有 std 或分配器的情况下也能构建。在 v0.7.0 中,默认会开启 DebugError 和 DisplayError,这两个错误 provider 会将错误格式化为 String。如果你的接线使用了其中任何一个,请开启 alloc feature:


        [dependencies]cgp = { version = "0.8.0", features = ["alloc"] }
      

更新属性语法与直接依赖​

#[use_type] 中的关联类型分隔符从 :: 改为 .:


        // v0.7.0#[use_type(HasErrorType::Error)]// v0.8.0#[use_type(HasErrorType.Error)]
      

相等性导入也使用新的分隔符。写作 #[use_type(HasErrorType.{Error = AppError})]。来自另一个上下文的导入形式也会变化,上下文用 in 命名:#[use_type(@Types::HasScalarType::Scalar)] 变为 #[use_type(HasScalarType.Scalar in Types)]。#[use_type] 参考文档涵盖了每种形式。

生成 UseDelegate dispatcher 的组件将 #[cgp_component] 的 derive_delegate key 移入它自己的属性,每个 dispatcher 一个:


        // v0.7.0#[cgp_component {    provider: AreaCalculator,    derive_delegate: UseDelegate<Shape>,}]// v0.8.0#[cgp_component(AreaCalculator)]#[derive_delegate(UseDelegate<Shape>)]
      

新组件不需要这两种形式,因为“其他改进”中的 open 语句会按类型进行分发。

extra-feature 宏 crate 从 cgp-extra-macro 和 cgp-extra-macro-lib 重命名为 cgp-macro-extra 和 cgp-macro-extra-lib。请更新对这些 crate 的直接依赖。通过 cgp::prelude 的导入保持其名称不变。

自包含的 handler 宏展开可能会留下未使用的导入。如果某些导入仅用于旧的展开,请移除编译器报告的这些导入。

#[cgp_auto_dispatch] 会拒绝属性参数和带类型的接收者,例如 self: Box<Self>。它之前会忽略这些参数,或对这些接收者产生错误编译。

文章标题:Context-Generic Programming (CGP) v0.8.0 - cargo-cgp、新文档与命名空间

正文: 新的 Struct! 和 Enum! prelude 导出可能使宏名称产生歧义。如果另一个 glob 导入提供了相同的名称,请对调用进行限定。

DelegateComponent、IsProviderFor、HasField 和 HasFieldMut 不再携带自定义的 #[diagnostic::on_unimplemented] 消息。普通的 cargo check 现在会以编译器自身的措辞报告它们上未满足的约束,而 cargo cgp check 会将这些错误重写为自己的摘要。如果有测试会比较编译器输出(就像 UI 测试那样),请更新它期望的消息。

检查错误后端行为​

cgp-error-eyre 启用了 eyre 的自动默认处理器安装,并跟踪 raise_error 和 wrap_error 的调用者。

cgp-error-std 改变了包装错误的显示方式。普通 Display 只打印外层细节,而备用 Display 和 Debug 会包含错误链。这避免了当报告器自身遍历 source() 时出现重复的来源。请更新依赖旧格式化的输出断言。

anyhow 和 eyre 的最低依赖版本分别升至 1.0.104 和 0.6.14。CGP 仓库中的后端 README 描述了它们的用法。

尝试你应用中的某一部分​

我们从两个 manager 选项开始,最终得到了可以共享核心、更改过滤器或使用不同数据库的应用。命名空间让顶层接线能够表达这些选择,即使我们将实现拆分成更小的部分。我希望这能让类似的重构在你自己的项目中更容易跟进,在遇到不清楚的地方时,有 cargo-cgp 和新文档提供帮助。

CGP 仍然需要时间学习。它的生态系统很小,我在工具和文档方面还有工作要做。我的建议是,在你已经遇到的一个问题上尝试它。如果你已经在使用 CGP,试着将接线中的某一个区域分组,同时保留其组件检查。如果你刚接触 CGP,Quickstart 提供了一个更小的起点。

我很乐意听取你在追踪实现、理解诊断信息或跟进解释时仍然感到困难的地方。这些例子将帮助我决定接下来改进什么。你可以在 GitHub Discussions 中分享它们。感谢你阅读并尝试 CGP。

我撰写了本文的草稿,一个 AI agent 修订了其文句,并对照 CGP 知识库检查了其代码和论断。参见 How AI is used in this project。

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by Lobsters
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗