dart-api-design（dart API 设计）

Designing Effective Dart APIs

Contents

• Naming Conventions
• Class Modifiers & Architecture
• Members & Encapsulation
• Types & Signatures
• Parameters
• Workflows

Naming Conventions

Enforce consistent, descriptive naming to leverage existing domain and core library knowledge.

• Properties & Variables:

- Use noun phrases for non-boolean properties (e.g., pageCount, context.lineWidth). - Use non-imperative verb phrases for boolean properties (e.g., isEmpty, canClose). Prefer the "positive" name (e.g., isConnected over isNotDisconnected).

• Methods & Functions:

- Use imperative verb phrases for side-effect-heavy operations (e.g., list.add(), window.refresh()). - Use noun phrases or non-imperative verb phrases if returning a value is the primary purpose (e.g., list.elementAt(3)). - AVOID starting method names with get. Use a getter or a descriptive verb (e.g., downloadData()). - Name methods to___() if they copy state to a new object (e.g., list.toSet()). - Name methods as___() if they return a different representation backed by the original object (e.g., table.asMap()).

• Type Parameters: Follow standard mnemonics: E (elements), K/V (key/value), R (return type), or T/S/U (single types).

Class Modifiers & Architecture

Design for extension and encapsulate implementations using Dart 3 class modifiers. Apply modifiers to control external library access.

• abstract: Use to define a class that requires concrete implementation of its interface. Cannot be instantiated.
• base: Use to enforce inheritance of a class's implementation. Disallows implements outside its own library. Guarantees the base class constructor is called.
• interface: Use to define a pure interface. Allows implements but disallows extends outside its library. Reduces the fragile base class problem.
• final: Use to close the type hierarchy. Disallows both extends and implements outside the library. Guarantees safe incremental API changes.
• sealed: Use to create a known, enumerable set of subtypes. Enables exhaustive switch statements over subtypes. Implicitly abstract.

*Note: Combine modifiers where appropriate (e.g., abstract interface class for a pure interface).*

Members & Encapsulation

• Encapsulation: AVOID public fields; use getters and setters for encapsulation to control state access and modification.
• Getters: Use getters for operations that conceptually access properties. The operation must take no arguments, return a result, have no user-visible side effects, and be idempotent.
• Setters: Use setters for operations that conceptually change properties. The operation must take a single argument, change state, and be idempotent.

- DON'T define a setter without a corresponding getter. - DON'T specify a return type for a setter (they inherently return void).

• Method Cascades: AVOID returning this from methods just to enable a fluent interface. Use Dart's cascade operator (..) instead.
• Equality:

- DO override hashCode if you override ==. - AVOID defining custom equality for mutable classes. - DON'T make the parameter to == nullable (the language handles null checks automatically).

Types & Signatures

• Type Aliases: DO use type aliases (typedef) to simplify complex function signatures. Use the modern syntax: typedef Comparison<T> = int Function(T a, T b);.
• Inline Functions: PREFER inline function types over typedefs for simple, one-off callbacks (e.g., void Function(Event) callback).
• Type Annotations:

- DO type annotate variables without initializers. - DO annotate return types and parameter types on non-local function declarations. - DON'T redundantly type annotate initialized local variables or inferred closure parameters.

• Generics: Write complete generic types. AVOID incomplete generic types (e.g., use Completer<Map<String, int>>() instead of Completer<Map>()).
• Dynamic vs. Object: AVOID using dynamic unless you explicitly want to disable static checking. Use Object? to accept any value safely.
• Async Returns: DO use Future<void> as the return type of asynchronous members that do not produce values. AVOID using FutureOr<T> as a return type (it forces callers to check the type).

Parameters

• Named Parameters: PREFER named parameters for functions with more than two arguments to improve call-site readability.
• Boolean Parameters: AVOID positional boolean parameters. Use named parameters instead.

- CONSIDER omitting the 'is/can/has' prefix from named boolean parameters (e.g., use Isolate.spawn(..., paused: true) instead of isPaused: true).

• Optional Positional Parameters: AVOID optional positional parameters if the user may want to omit earlier parameters. Use named parameters instead.
• Ranges: DO use inclusive start and exclusive end parameters to accept a range (e.g., substring(1, 3)).

Workflows

Task Progress: API Design & Implementation

Copy this checklist to track progress when designing a new Dart class or library API.

• Define Class Modifiers:

- If defining a contract without implementation -> abstract interface class. - If providing implementation that must be inherited -> base class. - If closing the hierarchy to external extension/implementation -> final class. - If defining an enumerable set of states for exhaustive switching -> sealed class.

• Encapsulate State:

- Make internal fields private (_fieldName). - Expose state via getters. - Expose mutations via setters (ensure a corresponding getter exists).

• Refine Signatures:

- Convert positional parameters to named parameters if > 2 arguments. - Convert positional booleans to named booleans (strip is/can/has prefixes). - Extract complex function parameters into typedef aliases.

• Verify Types:

- Ensure no implicit dynamic types exist in public signatures. - Replace FutureOr<T> return types with Future<T>. - Ensure async void methods return Future<void>.

• Run Validator -> Review Errors -> Fix:

- Run dart analyze to catch missing annotations, unhandled sealed class switch cases, and linter violations. Fix all warnings before finalizing the API.