rust-trait-api-design

Rust Trait API Design

Use this skill to make Rust APIs generic where useful, concrete where simpler, and object-safe when dynamic dispatch is part of the design. Optimize for the smallest capability contract that callers and implementors can understand.

Core Workflow

1. Identify whether the API consumes, borrows, returns, stores, or dispatches behavior.
2. Start with concrete types for local code. Generalize only when at least two callers or implementations need the flexibility.
3. Use generic bounds for compile-time polymorphism and inlining. Use dyn Trait for heterogeneous values, plugin-like extension points, or runtime dispatch.
4. Place bounds at the point that needs them. Prefer where clauses when bounds are long or involve associated types.
5. Decide whether a trait is intended for downstream implementation. Seal it, keep fields private, or use constructors when invariants must not be implemented externally.
6. Use standard conversion traits where they match exactly. Do not invent a custom conversion trait before checking From, TryFrom, AsRef, AsMut, Borrow, ToOwned, and Cow.
7. Add compile tests, unit tests, or examples that prove the public API is callable the way the skill expects future users to call it.

API Design Rules

• Accept impl Trait or a named generic for parameters when callers should pass many concrete types.
• Return impl Trait when hiding one concrete return type. Return Box<dyn Trait> when the concrete type varies at runtime.
• Prefer associated types when each implementation has one natural related type. Prefer generic trait parameters when one implementation supports many target types.
• Implement From for infallible conversions and TryFrom for fallible conversions. Implementing these gives callers Into and TryInto.
• Use AsRef for cheap reference-to-reference conversion. Use Borrow only when borrowed and owned forms have equivalent Eq, Hash, and Ord behavior.
• Avoid Copy bounds unless the algorithm semantically requires bitwise copy.

Trait Object Review

Read references/trait-api-patterns.md when choosing between generics and dyn Trait, or when public traits fail object-safety checks.

Before making a public trait object-safe, check:

• Methods do not use generic type parameters.
• Methods do not return Self unless constrained with where Self: Sized.
• Associated types are specified on the trait object where needed.
• The object is behind a pointer such as &dyn Trait, Box<dyn Trait>, or Arc<dyn Trait + Send + Sync>.

Common Smells

• A public function takes &Vec<T> because it only needs iteration.
• The API accepts String and immediately borrows it as &str.
• The API implements Into directly instead of From.
• A trait has many blanket bounds that only one method needs.
• A trait object was used because lifetimes were confusing, not because runtime dispatch is required.
• async-trait is used in a public trait without checking whether native async fn in traits, trait-variant, or boxed futures fit the dispatch and Send needs better.