Jon Chery
496303471d
---ci--- project: atelier phase: 7 milestone: v0.1 status: complete phase_role: final milestone_complete: true requirements: covered: [ATELIER-01, ATELIER-02, ATELIER-03, ATELIER-04, ATELIER-05, ATELIER-06, ATELIER-07, ATELIER-08, ATELIER-09, ATELIER-10, ATELIER-11, ATELIER-12, ATELIER-13, ATELIER-14, ATELIER-15, ATELIER-16, ATELIER-17, ATELIER-18, ATELIER-19, ATELIER-20, ATELIER-21, ATELIER-22, ATELIER-23, ATELIER-24, ATELIER-25, ATELIER-26, ATELIER-27, ATELIER-28, ATELIER-29, ATELIER-30, ATELIER-31, ATELIER-32, ATELIER-33, ATELIER-34, ATELIER-35] partial: [] ship: milestone: v0.1 type: NFR tag: v0.0.7 merge: milestone/v0.1-atelier -> main release: https://git.cloudinit.dev/cloudinit-bot/atelier/releases/tag/v0.0.7 ---/ci--- Milestone v0.1 — Initial Framework (NFR, complete). 8 core principles (C1-C8), 11 domains, 110 domain principles, 27 derived docs, 4 good + 3 bad examples, 4 language docs, full matrix, 3 review docs. All 35 requirements covered. 7 patches (v0.0.0 pre-execution through v0.0.7 final). v0.0.7 IS the v0.1.0 milestone release.
2.5 KiB
2.5 KiB
GraphQL — Derived Rules
Derives from
domains/api/first-principles.md. Applies P1–P10 to GraphQL specifically.
Schema First (P1 Contract Fidelity)
- The schema is the contract. Every field has a type, a description, and a deprecation status.
- The schema is versioned. Breaking schema changes (removing a field, changing a type) require a deprecation cycle.
- Never expose raw database types in the schema. Map them to domain types.
Query Design (P2 Clarity, P3 Predictability)
- Field names are nouns, camelCase:
userOrders, notUserOrdersoruser_orders. - Arguments are descriptive:
first,after,orderBy— notarg1,arg2. - Connections for lists:
users(first: 10, after: "cursor")— never bare arrays. - Mutations are verbs:
createUser,deleteOrder— notuserCreate.
N+1 Prevention (P7 Performance)
- Use a dataloader for every list field that resolves to another resource.
- A resolver that does a database query per item is an N+1 bug.
- Test resolvers under a list query, not just a single-item query.
Authorization at the Field Level (P8 Security)
- Every resolver checks authorization. The query graph is not a trust boundary by default.
- A user who can query
user { email }is not automatically authorized to queryuser { passwordHash }. - Field-level authz is the floor, not an optimization.
Deprecation (P5 Versioning, P10 Stability)
- Deprecate fields with
@deprecated(reason: "..."). Never remove a field without deprecating first. - A deprecated field is removed in the next major schema version, not sooner.
- Track field usage. A deprecated field with no usage can be removed sooner.
Error Handling (P9 Error Transparency)
- Errors are partial by default: a query can return data and errors simultaneously.
- Errors are structured:
{ message, path, extensions: { code, ... } }. - Use
extensions.codefor machine-consumable error types, not free-text messages. - Never swallow a resolver error silently. A null field with no error is a bug.
Complexity Budget (P7 Performance, P8 Security)
- Enforce a query complexity limit. Unbounded depth/breadth is a DoS vector.
- Cost-based analysis (not just depth) catches expensive nested queries.
- Reject queries over budget with a 400, not a 500.
Federation (P6 Composability)
- A federated subgraph owns its entities. Cross-graph references use
@externaland@requires. - Never reach into another subgraph's database. The graph boundary is the contract.
- The gateway composes; subgraphs do not know about each other.