rust-lombok-macros

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Rust Lombok Macros

Rust Lombok 宏

Treat

lombok-macros

as a procedural-macro dependency and API generator, not as a complete Rust equivalent of Java Lombok. Confirm every generated method's signature, visibility, failure behavior, and compatibility boundary before removing boilerplate.

将

lombok-macros

视为 procedural macro 依赖和 API 生成器，而不是 Java Lombok 在 Rust 中的完整等价物。在移除样板代码之前，确认每个生成方法的签名、可见性、失败行为和兼容性边界。

Scope

适用范围

Use this skill for:

DTOs, configuration snapshots, internal messages, test fixtures, and other data carriers where every field combination is valid;
reducing mechanical methods with
```
Getter
```
,
```
GetterMut
```
,
```
Setter
```
,
```
Data
```
, or
```
New
```
;
excluding explicitly identified sensitive fields with
```
CustomDebug
```
;
reviewing existing attributes, upgrading the crate, or migrating handwritten methods.

Do not generate methods blindly for:

domain entities, value objects, or security boundaries that require validation;
methods with stable public contracts, custom errors, auditing, or side effects;
```
Option
```
or
```
Result
```
access paths that must preserve absence or error information;
builders, default-value policies, serialization, comparisons, or hashing; version
```
2.0.32
```
does not provide these capabilities.

Route dependency versions, features, and supply-chain policy to

rust-cargo-build

; general procedural-macro implementation to

rust-macros

; API and security review to

rust-code-review

; and broader test design to

rust-testing

在以下场景中使用此 skill：

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

不要盲目为以下对象生成方法：

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

将依赖版本、feature 和供应链策略交由

rust-cargo-build

处理；将通用 procedural macro 实现交由

rust-macros

处理；将 API 和安全审查交由

rust-code-review

处理；将更广泛的测试设计交由

rust-testing

处理。

Workflow

工作流

1. Establish the exact baseline

1. 确定准确基线

Inspect the project instead of assuming a version:

bash

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

Check

Cargo.toml

Cargo.lock

, the edition,

rust-version

, and supported targets. Version

2.0.32

uses Edition 2024 and does not declare a Rust version, so compile it on the project's actual MSRV. Do not infer the selected version only from the current crates.io page or a GitHub release badge.

When adding the dependency, use

cargo add lombok-macros

or an explicit reviewed version such as

cargo add lombok-macros@2.0.32

. Never copy

lombok-macros = "latest"

into

Cargo.toml

; Cargo dependencies use semantic version requirements, not a

latest

keyword.

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

bash

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

检查

Cargo.toml

、

Cargo.lock

、edition、

rust-version

和支持的 target。版本

2.0.32

使用 Edition 2024，且未声明 Rust 版本，因此应在项目实际使用的 MSRV 上编译。不要仅根据当前 crates.io 页面或 GitHub release badge 推断所选版本。

添加依赖时，使用

cargo add lombok-macros

，或使用经过审查的明确版本，例如

cargo add lombok-macros@2.0.32

。绝不要将

lombok-macros = "latest"

复制到

Cargo.toml

；Cargo 依赖使用语义版本要求，而不是

latest

关键字。

2. Triage examples by crate version

2. 按 crate 版本分类示例

Do not assume that a blog post, generated answer, or older snippet matches the locked crate. In particular,

2.0.32

does not export a

Lombok

derive. Rewrite examples such as

#[derive(Lombok, Debug, Clone)]

with the smallest current derives, for example

#[derive(Getter, Setter, Debug, Clone)]

, or use

Data

only when mutable getters are also intended.

Keep capability ownership explicit:

```
Debug
```
and
```
Clone
```
are standard-library derives, not features generated by
```
lombok-macros
```
.
```
CustomDebug
```
is the crate-provided alternative when selected fields must be skipped.
```
DisplayDebug
```
and
```
DisplayDebugFormat
```
implement
```
Display
```
from an existing
```
Debug
```
representation; they do not make Debug output a stable presentation format.
A procedural macro removes handwritten source but still adds compile-time work and generated behavior. Do not describe it as cost-free without qualification.

不要假定博客文章、生成的答案或旧代码片段与锁定版本的 crate 一致。尤其是，

2.0.32

不导出

Lombok

derive。请使用当前最小的 derive 重写类似

#[derive(Lombok, Debug, Clone)]

的示例，例如

#[derive(Getter, Setter, Debug, Clone)]

；只有在还需要可变 getter 时才使用

Data

。

明确各项能力的归属：

```
Debug
```
和
```
Clone
```
是标准库 derive，并非
```
lombok-macros
```
生成的 feature。
```
CustomDebug
```
是 crate 提供的替代方案，用于跳过指定字段。
```
DisplayDebug
```
和
```
DisplayDebugFormat
```
基于现有的
```
Debug
```
表示实现
```
Display
```
；它们不会让 Debug 输出成为稳定的展示格式。
procedural macro 虽然移除了手写源代码，但仍会增加编译期工作和生成行为。不要在没有限定条件的情况下称其完全没有成本。

3. Inventory the pre-generation API

3. 盘点生成前的 API

Record each field's existing method signature, visibility, ownership behavior, validation, side effects, errors, and callers. Replace a method only when the generated interface is equivalent or the contract change has been accepted.

Select the smallest derive:

Requirement	Derive	Default risk
Read-only access	`Getter`	Default `Option` and `Result` getters unwrap and return the inner value
Mutable borrowing	`GetterMut`	Callers can bypass field invariants
Direct replacement	`Setter`	Setters do not validate and add write access
All three accessor types	`Data`	The API surface is often wider than necessary
All-field construction	`New`	The constructor is public by default; skipped fields use `Default`
Redacted debug output	`CustomDebug`	New sensitive fields still require explicit review
Debug reused as Display	`DisplayDebug*`	Structural output leaks easily and is not a stable user contract

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

选择最小的 derive：

需求	Derive	默认风险
只读访问	`Getter`	默认的 `Option` 和 `Result` getter 会 unwrap 并返回内部值
可变借用	`GetterMut`	调用方可以绕过字段不变量
直接替换	`Setter`	setter 不会验证数据，并增加写入访问能力
三种访问器全部需要	`Data`	API 表面通常比实际需要更宽
使用所有字段构造	`New`	构造函数默认公开；被跳过的字段使用 `Default`
隐藏 Debug 输出中的内容	`CustomDebug`	新增敏感字段后仍需明确审查
将 Debug 复用为 Display	`DisplayDebug*`	结构化输出容易泄露信息，且不是稳定的用户契约

4. Make generated semantics explicit

4. 明确生成语义

Write attributes against the locked version's source and documentation. For

2.0.32

rust

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,
}

Return
```
&T
```
for expensive values unless callers require ownership.
Use
```
type(clone)
```
only when cloning is part of the API contract.
Use
```
type(copy)
```
when value semantics are required for a
```
Copy
```
field.
Do not use the
```
#[get(pub, clone)]
```
shorthand shown in part of the documentation; the
```
2.0.32
```
parser requires
```
type(clone)
```
.
Use
```
type(Into<T>)
```
or
```
type(AsRef<T>)
```
for setter conversion, then compile the exact target type.
Keep visibility minimal. Generated public methods become part of a library's semver surface.

Read Macro Reference for the complete derive and attribute matrix.

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

2.0.32

：

rust

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 转换，然后编译准确的目标类型。
保持最小可见性。生成的 public 方法会成为 library 的 semver API 表面。

阅读宏参考，了解完整的 derive 和属性矩阵。

5. Preserve Rust invariants

5. 保持 Rust 不变量

Keep handwritten
```
new
```
or
```
try_new
```
functions when construction validates state.
Keep named methods when mutation requires validation, auditing, or coordinated field updates; do not generate
```
Setter
```
or
```
GetterMut
```
for those fields.
For
```
Option
```
and
```
Result
```
, write explicit
```
as_ref
```
,
```
as_deref
```
, or container-returning methods. Reject default getters and
```
type(deref)
```
when they introduce panic paths.
Mark keys, tokens, passwords, and personal data with
```
#[debug(skip)]
```
, then test formatted output. Review every new field later.
Write
```
Display
```
manually for CLI, user-facing error, or protocol output. Restrict
```
DisplayDebug
```
to internal diagnostics.

Read Adoption and Review when replacing existing methods or reviewing a pull request.

当构造过程需要验证状态时，保留手写的
```
new
```
或
```
try_new
```
函数。
当修改操作需要验证、审计或协调多个字段更新时，保留具名方法；不要为这些字段生成
```
Setter
```
或
```
GetterMut
```
。
对于
```
Option
```
和
```
Result
```
，编写显式的
```
as_ref
```
、
```
as_deref
```
或返回容器的方法。当默认 getter 和
```
type(deref)
```
会引入 panic 路径时，拒绝使用它们。
使用
```
#[debug(skip)]
```
标记 key、token、password 和个人数据，然后测试格式化输出。之后每新增一个字段，都应重新审查。
对于 CLI、面向用户的错误或协议输出，手动编写
```
Display
```
。仅将
```
DisplayDebug
```
限制在内部诊断场景中使用。

替换现有方法或审查 pull request 时，请阅读采用与审查。

6. Test the expanded contract through callers

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

Add tests that call generated methods instead of only checking that the derive compiles:

bash

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

Cover method visibility, return types, setter chaining, constructor argument order,

new(skip)

defaults, Debug redaction, and the continued enforcement of handwritten invariants. Rerun these contract tests after dependency upgrades. Use

cargo expand

for manual inspection when useful, but do not make a nightly-only tool the sole quality gate.

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

bash

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 的工具作为唯一的质量门禁。

Completion Criteria

完成标准

Confirm the dependency version, source, edition, and project MSRV with a real build.
Use the smallest derive instead of defaulting to
```
Data
```
.
Confirm every generated method's signature, visibility, ownership, and panic behavior.
Keep validation, invariants, side effects, and error semantics in explicit Rust code.
Prevent sensitive fields from reaching Debug or Display, and do not expose Debug as user output.
Pass fmt, check, test, and Clippy with tests that call the generated API.

通过真实构建确认依赖版本、来源、edition 和项目 MSRV。
使用最小的 derive，而不是默认采用
```
Data
```
。
确认每个生成方法的签名、可见性、所有权和 panic 行为。
在显式的 Rust 代码中保留验证、不变量、副作用和错误语义。
防止敏感字段进入 Debug 或 Display，并且不要将 Debug 作为用户输出公开。
fmt、check、test 和 Clippy 全部通过，并使用调用生成 API 的测试进行验证。

Resources

资源

Macro and Attribute Reference
Adoption, Migration, and Review Checklist
Execution Scenarios
```
examples/golden-lombok/
```
: a compilable contract example locked to
```
2.0.32
```
.

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

Upstream Sources

上游来源

crates.io: confirm the published version, checksum, license, repository, features, and dependency metadata.
docs.rs 2.0.32: inspect the public derive macros and version-specific rustdoc; avoid the moving
```
latest
```
URL during implementation.
GitHub source: inspect implementation history, tags, issues, and unreleased changes. Compare the matching release tag, not only the default branch.
Rust Reference: procedural macros

If prose, rustdoc examples, and behavior disagree, treat the source included in the selected crates.io package as authoritative for generated code, reproduce the behavior in a minimal compile test, and document the discrepancy. Never silently substitute GitHub

master

behavior for the version in

Cargo.lock

crates.io：确认已发布版本、校验和、license、repository、feature 和依赖元数据。
docs.rs 2.0.32：检查公开的 derive macro 和特定版本的 rustdoc；实现期间避免使用会指向最新版本的
```
latest
```
URL。
GitHub source：检查实现历史、tag、issue 和尚未发布的变更。应比较匹配的 release tag，而不是只比较默认分支。
Rust Reference: procedural macros

如果说明文字、rustdoc 示例和实际行为之间存在冲突，应以所选 crates.io package 中包含的源代码作为生成代码的权威依据，在最小编译测试中复现该行为，并记录差异。绝不能将 GitHub

master

分支的行为静默替换为

Cargo.lock

中版本的行为。

Data Privacy

数据隐私

This skill does not collect, store, or transmit user data. Dependency changes may access a registry. Confirm authorization before accessing a private registry, changing credentials, or publishing a crate.

此 skill 不会收集、存储或传输用户数据。依赖项变更可能会访问 registry。在访问私有 registry、修改凭据或发布 crate 之前，必须确认已获得授权。