Rust Types And Apis

Rust Types and APIs

Use this when the real question is how much of the design should be expressed in types, traits, and public signatures.

Working stance

• Make invalid states hard to represent before adding runtime checks.
• Keep public APIs narrower than internal helper code.
• Prefer concrete types until abstraction pressure is real.
• Use trait objects for extension seams and heterogeneity, not by reflex.
• Prefer typed domains and borrowed read-only inputs over stringly or collection-specific signatures.
• Accept broad inputs; return precise outputs.

Decision surface

• Generics: the caller should stay generic and one concrete type flows through each call site.
• dyn Trait: runtime heterogeneity, plugin seams, or monomorphization costs matter more than static dispatch.
• Newtype: domain distinction matters and misuse should not compile.
• Typestate: operation order is finite and important enough to encode.
• Sealed trait: downstream implementations would weaken invariants.
• AsRef or Into inputs: caller flexibility helps without hiding semantics.
• &str or &[T] inputs: prefer them over &String or &Vec<T> when the callee only reads.

Red flags

• public APIs expose internal helper traits or incidental generic parameters,
• public APIs accept &String or &Vec<T> where &str or &[T] would do,
• public functions take two or more bool parameters (boolean blindness: prefer named domain enums or an options struct),
• strings represent closed sets, validated IDs, or states that should be enums or newtypes,
• a trait object appears only to avoid naming a concrete type,
• boxed trait objects appear even though one concrete type or impl Trait would work,
• one implementation spawned a deep generic or trait abstraction anyway,
• newtypes exist but immediately expose raw fields everywhere,
• invariant-carrying types expose public fields directly,
• typestate multiplies boilerplate without enforcing a real rule,
• crate features change core semantics rather than optional integration.

Read generics-vs-dyn.md, newtypes-and-typestate.md, public-api-boundaries.md, and misuse-resistant-apis.md when one of those forks becomes the main design pressure. The last covers typestate, hidden-inner newtypes, anti-boolean-blindness, relevant API Guidelines tags, and SemVer tooling (cargo-semver-checks, cargo-public-api).

Source: leynos/rust-skill — distributed by TomeVault.