api-design

原文涵盖的主题

• API design
• 1. Model the domain, not the storage
• 2. Make the wrong call impossible
• 3. Design the errors as carefully as the successes
• 4. Plan for change on day one
• 5. Be boring and consistent
• 6. Decide the operational contract
• Report

An API is a promise. Implementation is cheap to change; a published interface is not, because every caller has to move with you. Design it as though you cannot change it, because roughly speaking you cannot. Design from the caller's side. Write the code that calls your API before you write the API. If that code is awkward, the design is wrong, and you have found out in two minutes instead of after three teams have integrated. The most common failure is exposing your database schema through HTTP. It couples every consumer to your internal structure, so a routine table split becomes everyone's migration. Name resources and operations in the language your users use, not your tables. If a caller must understand your persistence model to use the API, the abstraction has already failed. Done when: you could change the storage layer without touching the interface. Design so misuse does not compile, or fails immediately and clearly: Required things are required. Not optional-with-a-runtime-check. Enums over free strings for anything with a fixed set of values. Distinct types over booleans. create(user, true, false) is unreadable at the call site and easy to get backwards. No parameter whos

这里只展示节选，请以完整原文和当前要求为准。