Node.js添加notFoundHandler后GraphQL路径无法访问的问题求助

问题背景 #

在Node.js应用中集成GraphQL后，添加notFoundHandler()中间件导致localhost:3020/graphql端点无法访问，请求被错误路由到404处理逻辑。

问题原因分析 #

1. Apollo Server的server.start()是异步函数
2. 类的构造函数无法声明为async，无法直接等待异步操作完成
3. 构造函数中notFoundHandler(app)的执行早于setGraphQL()中异步完成的app.use('/graphql', ...)，导致所有未匹配到已有路由的请求（包括/graphql）先被404中间件拦截

应用环境：

• Node.js 20.10.0
• @apollo/server ^4.10.0
• Express ^4.18.2

已尝试的临时方案：将notFoundHandler(app)移到setGraphQL()的await server.start()之后调用，虽然可行但不符合中间件组织的最佳实践。

解决方案与最佳实践 #

1. 构造函数限制下启动GraphQL服务的替代方式 #

由于构造函数无法异步，推荐使用类初始化方法的模式，将异步逻辑从构造函数中剥离：

• 在类中新增一个init()异步方法，统一处理所有异步初始化逻辑
• 在实例化类后调用init()方法，而非在构造函数中执行所有操作

修改后的核心代码示例：

// www.mjs
import { Application } from './app.mjs'
const appInstance = new Application();
appInstance.init(); // 调用异步初始化方法

// app.mjs
import express from 'express';
import cors from 'cors';
import { ApolloServer } from '@apollo/server';
import { expressMiddleware } from '@apollo/server/express4';
import notFoundHandler from './notFound.handler.js';
import { graphQlSchema } from './schema.js';

const app = express();

class Application {
    constructor() {
        this.setExpress();
        this.setConfigs();
        this.setRoutes();
    }

    // 新增异步初始化方法，统一处理异步逻辑
    async init() {
        await this.setGraphQL();
        // 所有路由/中间件注册完成后，最后添加404兜底处理
        notFoundHandler(app);
    }

    setExpress() {
        const PORT = 3020;
        app.listen(PORT, () => console.log(`Server is running on port ${PORT}`));
    }

    setConfigs() {
        app.use(express.json());
        app.use(express.urlencoded({ extended: true }))
        app.use(cors())
    }

    setRoutes() {
        app.get('/', (req, res) => res.json("Welcome"))
    }

    async setGraphQL() {
        const server = new ApolloServer({
            schema: graphQlSchema
        })

        await server.start();
        app.use('/graphql', cors(), expressMiddleware(server));
    }
}
export { Application }

2. 异步操作与中间件顺序的最佳实践 #

Express中间件遵循注册顺序优先匹配的核心原则，需遵守以下规则：

• 所有业务路由、API端点（包括GraphQL）必须在404、全局错误处理等兜底中间件之前注册
• 异步初始化的路由/中间件，必须确保其注册完成后再挂载兜底中间件
• 避免将异步逻辑直接放在构造函数中，改用显式的异步初始化方法，保证流程可控

3. Apollo Server特定的配置调整 #

针对Apollo Server的异步启动特性，可使用官方提供的后台启动方法优化体验：
使用startInBackgroundHandlingStartupErrorsByLoggingAndFailingAllRequests方法替代await server.start()，该方法会在后台启动服务，同时在启动完成前拦截所有请求并返回503错误，避免请求被提前路由到404：

async setGraphQL() {
    const server = new ApolloServer({
        schema: graphQlSchema
    })

    // 后台启动服务，启动完成前返回503而非404
    await server.startInBackgroundHandlingStartupErrorsByLoggingAndFailingAllRequests();
    app.use('/graphql', cors(), expressMiddleware(server));
}

注意：此方法仅优化启动阶段的请求响应，仍需确保兜底中间件在所有路由之后注册。

内容的提问来源于stack exchange，提问作者Reza Hadipour