GraphQL 是什么：一份 schema 加一堆 resolverWhat GraphQL is: one schema plus a set of resolvers

The schema declares what types this service offers, what fields each type has, what type each field is, and whether it can be null. It is a contract, written in a syntax called SDL (Schema Definition Language).

The resolvers are a pile of functions that say how each field’s value actually gets produced. The schema says Order has a shippingInfo field; a resolver is what really goes to the shipping service and fetches it.

The two halves have to line up. A field that exists in the schema with no resolver returns null; a resolver whose name does not match the schema field name is never called at all — and nothing complains. The second one is the hardest class of GraphQL bug to track down, and a later Debug Lab drills it.

This is the whole of node-subgraph/src/schema.graphql, not one character changed. Lines 1–2, the extend schema @link part, are Federation-only — the next module covers them, so skip them for now:

type Order { ... } declares an object type. Every line inside the braces is a field, written as fieldName: Type.

Field types come in three kinds:

• Scalars — the built-in leaf types, nothing to expand further. GraphQL ships five: ID, String, Int, Float, Boolean. In this schema totalAmount: Float! and quantity: Int! are both scalars.
  Look at createdAt: String! — the timestamp is stored as a string, not as some DateTime type. GraphQL has no built-in date scalar.
• Object types — you can keep querying downward. items: [OrderItem!]! and shippingInfo: ShippingInfo are both object types.
• Enums — status: OrderStatus!, where the value can only be one of PENDING / PROCESSING / SHIPPED / DELIVERED / CANCELLED. Return a string that is not on that list and you get an error.

ID deserves its own note: it serialises to a string, but what it means is “this is an identifier, do not do arithmetic on it”. So the userId in getOrdersByUserId("123") is the string "123", not the number 123 — the exact opposite of the React exam, where Note.id is a number. Do not mix the two up.

Query and Mutation are two entry types fixed by convention. A client can only start from their fields.

• Query = read. This schema offers two entries: order(id: ID!): Order (one order by id, nullable — not found means null) and orders(userId: ID!): [Order!]! (a list for one user, not nullable).
• Mutation = write. There is only createOrder here. GraphQL does not force you to put writes under Mutation, but everybody follows the convention — and the fields of one Mutation run one after another, while Query fields run in parallel.

What sits inside the parentheses is an argument: order(id: ID!) means “calling this field requires a non-null ID”. A resolver reads arguments from its second parameter, args.

input OrderItemInput is an input type. The difference from type: an input can only be used as an argument, its fields can only be scalars, enums or other inputs, and it has no resolvers. This one input becomes a big trap later — the next lesson is all about it.

In REST, the server decides which fields GET /api/orders/456 returns. In GraphQL the client writes that itself:

Two consequences, and both of them show up in the exam:

1. Your resolver may never run. The client did not ask for shippingInfo, so that resolver is never executed — GraphQL calls resolvers on demand.
2. This is where N+1 comes from. Ask for the shippingInfo of 100 orders and the executor calls Order.shippingInfo 100 times. One sentence from the client, 100 requests on the backend. That is why this project needs DataLoader.

Now string all of it together. The diagram below is the full server-side journey of that second query (the one that asks for shippingInfo), in seven steps: