subgraph 是怎么跑起来的How a subgraph starts up

1. Read the schema file. readFileSync(join(__dirname, 'schema.graphql')), then gql(...) parses that string into an AST.
   (__dirname is not built in under ESM, so the code above computes one by hand with fileURLToPath(import.meta.url) — the standard move in an ESM project.)
2. Assemble the schema. buildSubgraphSchema([{ typeDefs, resolvers }]) — the key federation step, covered in the next section.
3. Create the ApolloServer with a formatError hook that logs each error’s message, code, path and correlationId on the server side.
4. Start the server, listening on 4000.
5. Build a context for every request (covered in the previous module).

That formatError block deserves a close look: it returns formattedError unchanged and only logs on the way past. Which means whatever you put into extensions inside a resolver reaches the client — the precondition for “structured errors” doing any good at all.

A plain GraphQL service uses makeExecutableSchema. A subgraph uses buildSubgraphSchema (from @apollo/subgraph). The second one does three extra things:

1. It understands the federation directives: @key, @external, @shareable and friends. A plain schema reports them as unknown directives.
2. It adds a _service field for you, returning this subgraph’s federation SDL. That field is how the Router collects schemas at startup.
3. It adds an _entities field for you, which takes a batch of entity representations and returns the matching objects. The Router uses it at runtime for cross-service entity resolution.

You do not write those two fields, and you should not. But you need to know they are there — they are the only door into verifying federation locally.

Way one: start the server and curl it. After npm start the server is on 4000, and index.js even prints the URL that queries the SDL.

Way two: execute in-process, no server at all. Build the schema with buildSubgraphSchema and run queries through graphql(). No port to occupy, no waiting for a server to come up, and you can run a whole series of queries from one script.

The script below is the verification tool I actually wrote during the audit. It walks every important federation path — including _entities, the request the Router would send. After you finish Task 1, write yourself something like it.

• Imports need the .js. from './resolvers/orderResolvers.js' — this project is native ESM ("type": "module") with no bundler, so the extension is mandatory. The Foundations course has a Debug Lab just for this.
• Top-level await works. const { url } = await startStandaloneServer(...) sits at module top level — an ESM-only ability, impossible in CommonJS.

Also notice the NODE_OPTIONS=--experimental-vm-modules in that npm test script — jest needs it to run ESM. None of this config is yours to change, but you should recognise it.