docs: API design patterns from rust-lang/rust

10 patterns, 596 lines. Full spec compliance. Patterns: naming conventions, #[non_exhaustive], pub(crate), constructors, method chaining, trait bounds, typestate, extension traits, newtype, per-module errors.
2026-04-30 15:10:23 -07:00
parent 9cd0a33ff9
commit 7016c427e8
1 changed files with 596 additions and 0 deletions
@@ -0,0 +1,596 @@
+# Rust API Design Patterns
+
+Patterns for designing public APIs in Rust, extracted from the
+standard library source.
+
+**Source:** [rust-lang/rust](https://github.com/rust-lang/rust) at commit
+[`f53b654`](https://github.com/rust-lang/rust/tree/f53b654a8882fd5fc036c4ca7a4ff41ce32497a6)
+
+**Stats:** 18,430 pub fn, 919 pub(crate), 53 #[non_exhaustive],
+889 is_/as_/to_/into_ methods, 162 new/build constructors,
+2,676 impl blocks.
+
+---
+
+## 1. Naming Conventions (is_, as_, to_, into_)
+
+### Source:
+
+889 methods following these naming conventions in library/.
+
+```rust
+impl Option<T> {
+    pub fn is_some(&self) -> bool { ... }     // is_ → bool check
+    pub fn as_ref(&self) -> Option<&T> { ... } // as_ → cheap ref conversion
+}
+
+impl String {
+    pub fn as_str(&self) -> &str { ... }      // as_ → borrow (no allocation)
+    pub fn into_bytes(self) -> Vec<u8> { ... } // into_ → consuming conversion
+}
+
+impl Path {
+    pub fn to_str(&self) -> Option<&str> { ... }     // to_ → potentially expensive
+    pub fn to_string_lossy(&self) -> Cow<str> { ... } // to_ → may allocate
+}
+```
+
+### Why
+
+The prefix tells you the cost and ownership semantics without
+reading the implementation:
+
+- `is_` → Returns bool, no allocation, &self
+- `as_` → Cheap conversion, returns a reference, &self
+- `to_` → Potentially expensive, may allocate, &self
+- `into_` → Consumes self, zero-cost ownership transfer
+
+### When to Use
+
+**Triggers:**
+- `is_`: Predicate (yes/no check on &self)
+- `as_`: Cheap view (reinterpret bits, return &T)
+- `to_`: Conversion that may allocate or compute (returns owned)
+- `into_`: Consuming conversion (self → OtherType)
+
+**Example — before:**
+```rust
+impl Email {
+    fn get_domain(&self) -> &str { ... }    // "get" prefix — Java style
+    fn make_lowercase(self) -> Email { ... } // "make" — unclear cost
+    fn check_valid(&self) -> bool { ... }   // "check" — inconsistent
+}
+```
+
+**Example — after:**
+```rust
+impl Email {
+    fn as_domain(&self) -> &str { ... }     // as_ → cheap, returns ref
+    fn into_lowercase(self) -> Email { ... } // into_ → consumes self
+    fn is_valid(&self) -> bool { ... }      // is_ → predicate
+    fn to_ascii(&self) -> String { ... }    // to_ → allocates new String
+}
+```
+
+### When NOT to Use
+
+**Don't use this when:**
+- The method doesn't fit any prefix (use a descriptive verb)
+- `new` for constructors (not `create_` or `make_`)
+- `get`/`set` for simple field access on non-collection types
+
+---
+
+## 2. #[non_exhaustive] for Future-Proof Enums
+
+### Source:
+
+[library/std/src/io/error.rs](https://github.com/rust-lang/rust/blob/f53b654a8882fd5fc036c4ca7a4ff41ce32497a6/library/std/src/io/error.rs) (ErrorKind)
+
+53 `#[non_exhaustive]` annotations in the stdlib.
+
+```rust
+#[non_exhaustive]
+pub enum ErrorKind {
+    NotFound,
+    PermissionDenied,
+    ConnectionRefused,
+    // ... can add more variants without breaking downstream
+}
+```
+
+### Why
+
+Without `#[non_exhaustive]`, adding an enum variant is a breaking
+change (downstream `match` statements become non-exhaustive).
+With it, match statements require a wildcard arm `_ =>`, so you
+can add variants freely in minor versions.
+
+### When to Use
+
+**Triggers:**
+- Public enums in libraries that may grow
+- Error kind enums (new error types are common)
+- Status/state enums that evolve over time
+- Struct fields you might add to later
+
+**Example — before:**
+```rust
+pub enum Color { Red, Green, Blue }
+// Later, adding Yellow breaks ALL downstream match statements:
+// error: non-exhaustive patterns: `Yellow` not covered
+```
+
+**Example — after:**
+```rust
+#[non_exhaustive]
+pub enum Color { Red, Green, Blue }
+// Downstream must have wildcard:
+match color {
+    Color::Red => "red",
+    Color::Green => "green",
+    Color::Blue => "blue",
+    _ => "unknown",  // required — handles future variants
+}
+// Adding Color::Yellow in next release is non-breaking!
+```
+
+### When NOT to Use
+
+**Don't use this when:**
+- The enum is closed (boolean-like: On/Off)
+- Internal use only (pub(crate))
+- You WANT exhaustive matching for safety (Option, Result)
+
+---
+
+## 3. pub(crate) for Internal Visibility
+
+### Source:
+
+919 `pub(crate)` usages in the stdlib.
+
+```rust
+pub(crate) fn internal_helper() { ... }
+pub(crate) struct InternalState { ... }
+```
+
+### Why
+
+`pub(crate)` makes items visible within the crate but not to
+external users. It's the middle ground between `pub` (everyone)
+and private (only the module). Keeps internal architecture
+flexible without exposing implementation details.
+
+### When to Use
+
+**Triggers:**
+- Helper functions used across modules but not part of the public API
+- Internal types that multiple modules need but users shouldn't see
+- Test utilities that need cross-module access
+
+**Example — before:**
+```rust
+// Private — can't use from sibling modules
+fn helper() { ... }
+
+// Public — now it's part of your API contract forever
+pub fn helper() { ... }
+```
+
+**Example — after:**
+```rust
+// Visible to the whole crate, invisible to users
+pub(crate) fn helper() { ... }
+```
+
+### When NOT to Use
+
+**Don't use this when:**
+- The item is only used in one module (just make it private)
+- The item should be part of the public API (use `pub`)
+- You're in a binary crate (there are no external users anyway)
+
+---
+
+## 4. Constructor Pattern (fn new)
+
+### Source:
+
+162 `new`/`build` methods in the stdlib.
+
+```rust
+impl Vec<T> {
+    pub const fn new() -> Self {
+        Vec { ptr: NonNull::dangling(), len: 0, cap: 0 }
+    }
+
+    pub fn with_capacity(capacity: usize) -> Self { ... }
+}
+```
+
+### Why
+
+`new()` is the standard constructor name in Rust (not `create`,
+`init`, `make`). Parameterized constructors use `with_` prefix or
+a builder pattern. `new()` should be cheap and infallible when
+possible.
+
+### When to Use
+
+**Triggers:**
+- `new()` — default or minimal construction
+- `with_capacity()` — pre-allocating variant
+- `from_*()` — construction from specific inputs (not From trait)
+- Builder pattern — many optional parameters
+
+**Example — before:**
+```rust
+impl Server {
+    pub fn create(host: &str, port: u16, threads: usize, tls: bool) -> Self { ... }
+    // 4 positional parameters — easy to mix up port and threads
+}
+```
+
+**Example — after:**
+```rust
+impl Server {
+    pub fn new(addr: SocketAddr) -> Self { ... }  // minimal required args
+
+    pub fn builder() -> ServerBuilder { ... }  // for complex configuration
+}
+
+impl ServerBuilder {
+    pub fn threads(mut self, n: usize) -> Self { self.threads = n; self }
+    pub fn tls(mut self, enabled: bool) -> Self { self.tls = enabled; self }
+    pub fn build(self) -> Result<Server, ConfigError> { ... }
+}
+```
+
+### When NOT to Use
+
+**Don't use this when:**
+- Construction can fail (use `try_new()` → Result, or builder with
+  fallible `build()`)
+- Multiple constructors exist (use descriptive names: `from_path`,
+  `from_reader`)
+
+---
+
+## 5. Method Chains (Consuming Self → Self)
+
+### Source:
+
+Iterator adapters are the definitive example of method chaining.
+
+```rust
+let result: Vec<i32> = vec![1, 2, 3, 4, 5]
+    .into_iter()
+    .filter(|x| x % 2 == 0)
+    .map(|x| x * x)
+    .collect();
+```
+
+### Why
+
+Method chaining creates fluent, readable APIs. Each method
+consumes self and returns a new (or modified) Self. The ownership
+model makes this natural — no mutation through shared references.
+
+### When to Use
+
+**Triggers:**
+- Builder patterns (each step returns modified builder)
+- Iterator adapters (each step wraps the previous)
+- Configuration objects
+
+**Example — before:**
+```rust
+let mut query = Query::new("users");
+query.set_filter("age > 18");
+query.set_limit(10);
+query.set_order("name");
+let results = query.execute()?;
+```
+
+**Example — after:**
+```rust
+let results = Query::new("users")
+    .filter("age > 18")
+    .limit(10)
+    .order_by("name")
+    .execute()?;
+```
+
+### When NOT to Use
+
+**Don't use this when:**
+- Operations can fail mid-chain (errors get awkward)
+- The object needs to be reused after each call
+- It makes the code LESS readable (very long chains)
+
+---
+
+## 6. Generic Parameters with Trait Bounds
+
+### Source:
+
+```rust
+// Accept anything that can be referenced as a Path:
+pub fn read<P: AsRef<Path>>(path: P) -> io::Result<Vec<u8>> { ... }
+
+// Accept anything comparable:
+pub fn max<T: Ord>(a: T, b: T) -> T { ... }
+
+// Multiple bounds:
+pub fn sort_and_print<T: Ord + Display>(items: &mut [T]) { ... }
+```
+
+### Why
+
+Generics with trait bounds give you maximum flexibility while
+maintaining type safety. The function works with ANY type that
+satisfies the bounds — but the compiler still checks everything
+at compile time.
+
+### When to Use
+
+**Triggers:**
+- Function should work with multiple concrete types
+- You want to accept user-defined types that implement your trait
+- Performance (monomorphization — no virtual dispatch)
+
+**Example — before:**
+```rust
+// Only works with String — can't pass &str, PathBuf, etc.
+fn log_to_file(path: String, message: String) { ... }
+```
+
+**Example — after:**
+```rust
+// Works with any type that can cheaply become &Path and &str
+fn log_to_file(path: impl AsRef<Path>, message: impl AsRef<str>) {
+    let path = path.as_ref();
+    let message = message.as_ref();
+    // ...
+}
+// Now accepts: "file.txt", String::from("file.txt"), PathBuf, etc.
+```
+
+### When NOT to Use
+
+**Don't use this when:**
+- Only one type will ever be used (concrete type is simpler)
+- You need dynamic dispatch (use `dyn Trait` instead)
+- The generic makes the signature unreadable (too many bounds)
+
+---
+
+## 7. Typestate Pattern (Compile-Time State Machines)
+
+### Source:
+
+The stdlib uses this in `File` (open modes) and throughout.
+The pattern encodes state in the type system.
+
+```rust
+// Different types for different states — impossible to misuse
+struct Connection<State> { inner: TcpStream, _state: PhantomData<State> }
+struct Connecting;
+struct Connected;
+struct Authenticated;
+
+impl Connection<Connecting> {
+    fn connect(addr: &str) -> Result<Connection<Connected>, Error> { ... }
+}
+impl Connection<Connected> {
+    fn authenticate(self, creds: &Creds) -> Result<Connection<Authenticated>, Error> { ... }
+}
+impl Connection<Authenticated> {
+    fn query(&self, sql: &str) -> Result<Rows, Error> { ... }
+}
+// Can't call query() without authenticating first — compile error!
+```
+
+### Why
+
+The type system prevents invalid state transitions. You literally
+cannot call methods in the wrong order because they don't exist on
+that type state. Bugs become compile errors.
+
+### When to Use
+
+**Triggers:**
+- State machine with ordered transitions
+- Protocol sequences (connect → auth → use)
+- Builder with required steps
+
+### When NOT to Use
+
+**Don't use this when:**
+- States are dynamic (determined at runtime)
+- There are too many states (exponential type explosion)
+- The API becomes confusing (type parameters everywhere)
+
+---
+
+## 8. Extension Traits for Adding Methods
+
+### Source:
+
+```rust
+// std adds methods to Iterator via extension traits:
+pub trait IteratorExt: Iterator + Sized {
+    fn take_while_ref<P>(&mut self, pred: P) -> TakeWhileRef<Self, P> { ... }
+}
+impl<I: Iterator> IteratorExt for I {}
+```
+
+### Why
+
+Extension traits add methods to types you don't own (from another
+crate) without modifying the original. Users must import the
+extension trait to see the methods.
+
+### When to Use
+
+**Triggers:**
+- Adding methods to external types (from other crates)
+- Optional functionality (only available when you import the trait)
+- Platform-specific extensions (e.g., `std::os::unix::fs::PermissionsExt`)
+
+### When NOT to Use
+
+**Don't use this when:**
+- You own the type (just add methods directly)
+- A free function would be clearer
+- The extension is confusing (users won't find it via autocomplete)
+
+---
+
+## 9. Newtype Pattern for Type Safety
+
+### Source:
+
+```rust
+// Newtype: single-field tuple struct
+pub struct Instant(time::Instant);
+pub struct Duration { secs: u64, nanos: Nanoseconds }
+
+// Newtypes prevent mixing up semantically different values:
+struct Meters(f64);
+struct Seconds(f64);
+// Can't accidentally pass Meters where Seconds is expected
+```
+
+### Why
+
+Newtypes create distinct types with zero runtime cost (same
+representation). They prevent confusing values that have the same
+underlying type but different semantics.
+
+### When to Use
+
+**Triggers:**
+- Multiple parameters of the same primitive type (easy to swap)
+- Domain concepts that should be distinct (UserID vs PostID)
+- Adding methods or trait impls to foreign types
+
+**Example — before:**
+```rust
+fn schedule_meeting(room_id: u64, user_id: u64, duration_mins: u64) { ... }
+// Easy to accidentally swap room_id and user_id — both are u64!
+schedule_meeting(user_id, room_id, 60);  // compiles fine — but wrong
+```
+
+**Example — after:**
+```rust
+struct RoomId(u64);
+struct UserId(u64);
+struct Minutes(u64);
+
+fn schedule_meeting(room: RoomId, user: UserId, duration: Minutes) { ... }
+// schedule_meeting(user_id, room_id, Minutes(60));  // COMPILE ERROR
+```
+
+### When NOT to Use
+
+**Don't use this when:**
+- Only one parameter of that type exists (no confusion possible)
+- The wrapper adds no safety (just wrapping for the sake of it)
+- The ergonomic cost (`.0` access, impl forwarding) outweighs benefit
+
+---
+
+## 10. Error Type Design (Per-Module Errors)
+
+### Source:
+
+The stdlib provides one error type per module: `io::Error`,
+`fmt::Error`, `num::ParseIntError`, `str::Utf8Error`.
+
+```rust
+// Each module has its own error type:
+pub mod io {
+    pub struct Error { repr: Repr }
+    pub type Result<T> = std::result::Result<T, Error>;
+}
+
+pub mod num {
+    pub struct ParseIntError { kind: IntErrorKind }
+}
+```
+
+### Why
+
+Per-module errors keep error types focused. `io::Error` handles
+all I/O errors with a kind enum + optional payload. This is more
+maintainable than one giant application error enum.
+
+### When to Use
+
+**Triggers:**
+- Your module is self-contained with its own failure modes
+- Different modules have different error semantics
+- You want to provide `type Result<T>` convenience alias
+
+### When NOT to Use
+
+**Don't use this when:**
+- The module is tiny (just use the parent's error type)
+- Errors need to compose across modules (consider `thiserror`/`anyhow`)
+
+---
+
+## Summary: API Design Decision Tree
+
+```
+Naming a method?
+├── Returns bool? → is_*
+├── Returns &T (cheap)? → as_*
+├── Returns T (may allocate)? → to_*
+├── Consumes self → T? → into_*
+├── Constructor? → new / with_* / from_*
+└── Other? → descriptive_verb
+
+Visibility?
+├── External API → pub
+├── Cross-module internal → pub(crate)
+└── Module-only → private (default)
+
+Enum might grow?
+└── YES → #[non_exhaustive]
+
+Many parameters?
+└── YES → Builder pattern (fn builder() → Builder)
+
+Accept multiple types?
+├── Cheap reference → impl AsRef<T>
+├── Ownership transfer → impl Into<T>
+└── Multiple bounds → T: Bound1 + Bound2
+
+Prevent misuse?
+├── Wrong argument order → Newtype pattern
+├── Wrong method order → Typestate pattern
+└── Future compatibility → #[non_exhaustive]
+```
+
+| Pattern | Use when |
+|---|---|
+| `is_`/`as_`/`to_`/`into_` | Standard naming convention |
+| `#[non_exhaustive]` | Enum/struct may gain variants/fields |
+| `pub(crate)` | Internal cross-module access |
+| `fn new` / builder | Construction |
+| Method chaining | Fluent APIs (config, queries, iterators) |
+| Trait bounds | Generic functions accepting multiple types |
+| Typestate | Compile-time state machine enforcement |
+| Extension traits | Adding methods to foreign types |
+| Newtype | Type-safe wrappers around primitives |
+| Per-module errors | Self-contained error types per module |
+
+See also:
+- [traits.md](traits.md) — Trait design patterns
+- [error-handling.md](error-handling.md) — Error type design
+- [documentation.md](documentation.md) — Documenting public APIs
+
+<!-- PATTERN_COMPLETE -->