rust-lombok-macros

Rust Lombok 宏

应将 lombok-macros 视为过程宏依赖和 API 生成器，而非完整的 Java Lombok Rust 等价物。移除样板代码前，请确认每个生成方法的签名、可见性、失败行为和兼容性边界。

范围

在以下场景使用此技能：

• DTO、配置快照、内部消息、测试夹具以及其他所有字段组合均有效的数据载体；
• 使用 Getter、GetterMut、Setter、Data 或 New 减少机械性方法；
• 使用 CustomDebug 排除明确标识的敏感字段；
• 审查现有属性、升级 crate 或迁移手写方法。

不要盲目生成以下内容的方法：

• 需要验证的领域实体、值对象或安全边界；
• 具有稳定公共契约、自定义错误、审计或副作用的方法；
• 必须保留缺失信息或错误信息的 Option 或 Result 访问路径；
• 构建器、默认值策略、序列化、比较或哈希；版本 2.0.32 不提供这些功能。

依赖版本、功能和供应链策略应交由 rust-cargo-build 处理；通用过程宏实现应交由 rust-macros 处理；API 和安全审查应交由 rust-code-review 处理；更广泛的测试设计应交由 rust-testing 处理。

工作流

1. 确认准确的基线

检查项目，而不要假定版本：

rustc --version --verbose
cargo metadata --format-version 1
cargo tree -i lombok-macros -e features

检查 Cargo.toml、Cargo.lock、Edition、rust-version 和支持的目标平台。版本 2.0.32 使用 Edition 2024，且未声明 Rust 版本，因此应在项目实际的 MSRV 下编译。不要只根据当前 crates.io 页面或 GitHub 发布徽章推断选定的版本。

添加依赖时，使用 cargo add lombok-macros 或明确指定经过审核的版本，例如 cargo add [email protected]。切勿将 lombok-macros = "latest" 复制到 Cargo.toml；Cargo 依赖使用语义化版本要求，而不是 latest 关键字。

2. 按 crate 版本筛选示例

不要假定博客文章、生成的回答或旧代码片段与锁定的 crate 版本一致。特别是，2.0.32 不会导出 Lombok 派生宏。请用当前最精简的派生宏重写 #[derive(Lombok, Debug, Clone)] 等示例，例如 #[derive(Getter, Setter, Debug, Clone)]；或者仅在也需要可变 getter 时使用 Data。

明确区分功能归属：

• Debug 和 Clone 是标准库派生宏，不是 lombok-macros 生成的功能。
• 当需要跳过指定字段时，CustomDebug 是该 crate 提供的替代方案。
• DisplayDebug 和 DisplayDebugFormat 会根据现有的 Debug 表示实现 Display；它们不会使 Debug 输出成为稳定的展示格式。
• 过程宏会减少手写源代码，但仍会增加编译时工作量并生成行为。除非加以限定，否则不要称其为零成本。

3. 盘点生成前的 API

记录每个字段现有方法的签名、可见性、所有权行为、验证、副作用、错误和调用方。只有在生成的接口等效，或契约变更已获认可时，才替换方法。

选择所需的最小派生宏：

要求	派生宏	默认风险
只读访问	Getter	默认情况下，Option 和 Result getter 会解包并返回内部值
可变借用	GetterMut	调用方可以绕过字段不变量
直接替换	Setter	setter 不会执行验证，并增加写入访问
三种访问器类型	Data	API 面通常比实际所需更广
全字段构造	New	构造函数默认是公开的；跳过的字段使用 Default
隐去敏感信息的调试输出	CustomDebug	新增的敏感字段仍需明确审查
将 Debug 复用于 Display	DisplayDebug*	结构化输出很容易泄露信息，且不是稳定的用户契约

4. 明确生成语义

根据锁定版本的源代码和文档编写属性。对于 2.0.32：

use lombok_macros::{CustomDebug, Getter, New, Setter};

#[derive(Getter, Setter, New, CustomDebug)]
#[new(pub(crate))]
struct WorkerConfig {
    #[get(pub)]
    #[set(pub, type(Into<String>))]
    name: String,

    #[get(pub, type(copy))]
    #[set(pub)]
    workers: usize,

    #[debug(skip)]
    #[new(skip)]
    token: String,
}

• 对开销较大的值返回 &T，除非调用方需要所有权。
• 仅当克隆属于 API 契约的一部分时，才使用 type(clone)。
• 当 Copy 字段需要值语义时，使用 type(copy)。
• 不要使用部分文档中展示的 #[get(pub, clone)] 简写；2.0.32 的解析器要求使用 type(clone)。
• 使用 type(Into<T>) 或 type(AsRef<T>) 进行 setter 转换，然后编译确切的目标类型。
• 尽量缩小可见范围。生成的公共方法会成为库 semver 接口的一部分。

阅读 宏参考，了解完整的派生宏和属性对照表。

5. 保留 Rust 不变量

• 如果构造过程会验证状态，则保留手写的 new 或 try_new 函数。
• 如果修改需要验证、审计或协调多个字段的更新，则保留具名方法；不要为这些字段生成 Setter 或 GetterMut。
• 对于 Option 和 Result，编写显式的 as_ref、as_deref 或返回容器的方法。如果默认 getter 和 type(deref) 会引入 panic 路径，则不要使用它们。
• 使用 #[debug(skip)] 标记密钥、令牌、密码和个人数据，然后测试格式化输出。之后还要检查每个新增字段。
• 对于 CLI、面向用户的错误或协议输出，手动编写 Display。仅将 DisplayDebug 用于内部诊断。

在替换现有方法或审查拉取请求时，请阅读 采用与审查。

6. 通过调用方测试扩展后的契约

添加调用生成方法的测试，而不只是检查派生宏能否编译：

cargo fmt --all --check
cargo check --workspace --all-targets --all-features
cargo test --workspace --all-targets --all-features
cargo clippy --workspace --all-targets --all-features -- -D warnings

覆盖方法可见性、返回类型、setter 链式调用、构造函数参数顺序、new(skip) 默认值、Debug 脱敏，以及手写不变量是否仍得到强制执行。升级依赖项后，重新运行这些契约测试。必要时使用 cargo expand 手动检查，但不要将仅适用于 nightly 的工具作为唯一的质量门槛。

完成标准

• 通过实际构建确认依赖项版本、源代码、Edition 和项目 MSRV。
• 使用最精简的派生宏，不要默认使用 Data。
• 确认每个生成方法的签名、可见性、所有权和 panic 行为。
• 将验证、不变量、副作用和错误语义保留在显式的 Rust 代码中。
• 避免敏感字段进入 Debug 或 Display，且不要将 Debug 用作面向用户的输出。
• 使用会调用生成 API 的测试，通过 fmt、check、test 和 Clippy。

资源

• 宏与属性参考
• 采用、迁移与审查检查清单
• 执行场景
• examples/golden-lombok/：锁定到 2.0.32 的可编译契约示例。

上游来源

• crates.io：确认已发布版本、校验和、许可证、仓库、功能和依赖元数据。
• docs.rs 2.0.32：检查公共派生宏和特定版本的 rustdoc；实现期间避免使用会变动的 latest URL。
• GitHub 源代码：检查实现历史、标签、问题和未发布的更改。对照匹配的发布标签，而不只是默认分支。
• Rust 参考：过程宏

如果说明文字、rustdoc 示例和实际行为不一致，应以所选 crates.io 软件包中包含的源代码作为生成代码的权威依据，通过最小化的编译测试复现该行为，并记录差异。切勿在未说明的情况下，用 GitHub master 的行为替代 Cargo.lock 中版本的行为。

数据隐私

此技能不会收集、存储或传输用户数据。依赖项变更可能会访问注册表。访问私有注册表、更改凭据或发布 crate 前，请先确认已获得授权。