Node.js中控制器与服务同名函数的最佳实践处理方案

我使用Node.js和Fastify已有数周，目前正在学习相关最佳实践，此前有PHP/Laravel开发背景。我将项目拆分为路由、控制器和服务（对应Laravel中的模型）。发现控制器与服务中使用同名函数会引发问题，代码会执行服务中的函数而非控制器中的。请问无需修改函数名的情况下，该问题通常如何处理？

现有代码 #

Router - /router/transactions.js #

function routes(fastify, options, done) {

    fastify.register(require('@fastify/formbody'))
    fastify.register(require('../controllers/transactions'))

    fastify.post('/get-initial-transaction', (req, rep) => {
        getInitialTransaction(req.body, rep)
    })

    done()
}

module.exports = routes

Controller - /controllers/transactions.js #

controller = (fastify, options, done) => {

    const service = fastify.register(require('../services/transactions'))

    getInitialTransaction = (req, rep) => {  
        rep.send(getInitialTransaction(req.uuid));
    }

    done()
}

module.exports = controller

Service - /services/transactions.js #

const service = (fastify, options, done) => {

    getInitialTransaction = (uuid) => {
        fastify.mysql.query(
            `SELECT t.amount, t.currency, t.reference, m.name
            FROM transactions t
            JOIN merchants m 
            ON m.id = t.merchant_id
            WHERE t.uuid = :uuid
            AND t.status_desc = "INITIAL"`, { uuid: uuid },
            function onResult(err, result) {
                if (!err) {
                    return (result[0])
                }
                else {
                    return (err)
                }
            }
        )
    }

    done()
}

module.exports = service

核心问题是全局变量污染：所有未用let/const/var声明的函数会自动挂载到Node.js的global全局对象。当你先注册控制器、再注册服务时，服务里的getInitialTransaction会覆盖控制器中同名的全局函数，导致路由调用的是服务版本的函数；同时控制器内部调用同名函数时，也会优先取全局的服务版本，形成逻辑错误。

利用Fastify的实例装饰器功能，把控制器和服务的方法分别挂载到fastify实例的不同命名空间下，通过命名空间区分同名函数，彻底避免全局污染。

1. 修改服务模块：用装饰器挂载服务方法 #

// /services/transactions.js
const service = (fastify, options, done) => {
    // 封装服务方法到局部作用域
    const getInitialTransaction = (uuid) => {
        // 修正异步逻辑：mysql.query是回调式异步，改用Promise包裹才能返回结果
        return new Promise((resolve, reject) => {
            fastify.mysql.query(
                `SELECT t.amount, t.currency, t.reference, m.name
                FROM transactions t
                JOIN merchants m 
                ON m.id = t.merchant_id
                WHERE t.uuid = :uuid
                AND t.status_desc = "INITIAL"`, 
                { uuid: uuid },
                function onResult(err, result) {
                    if (!err) {
                        resolve(result[0])
                    } else {
                        reject(err)
                    }
                }
            )
        })
    }

    // 把服务方法装饰到fastify实例的transactionService命名空间
    fastify.decorate('transactionService', {
        getInitialTransaction
    })

    done()
}

module.exports = service

2. 修改控制器模块：用装饰器挂载控制器方法，通过命名空间调用服务方法 #

// /controllers/transactions.js
const controller = (fastify, options, done) => {
    // 先注册服务模块
    fastify.register(require('../services/transactions'))

    // 封装控制器方法到局部作用域
    const getInitialTransaction = async (req, rep) => {  
        try {
            // 通过命名空间调用服务的同名方法
            const result = await fastify.transactionService.getInitialTransaction(req.uuid)
            rep.send(result)
        } catch (err) {
            rep.code(500).send({ error: err.message })
        }
    }

    // 把控制器方法装饰到fastify实例的transactionController命名空间
    fastify.decorate('transactionController', {
        getInitialTransaction
    })

    done()
}

module.exports = controller

3. 修改路由模块：通过命名空间调用控制器方法 #

// /router/transactions.js
function routes(fastify, options, done) {

    fastify.register(require('@fastify/formbody'))
    fastify.register(require('../controllers/transactions'))

    fastify.post('/get-initial-transaction', async (req, rep) => {
        // 通过命名空间调用控制器的方法
        await fastify.transactionController.getInitialTransaction(req, rep)
    })

    done()
}

module.exports = routes

• 异步逻辑修正：原服务中mysql.query是回调式异步，直接return无法拿到结果，必须用Promise包裹配合async/await，否则控制器会返回undefined给客户端。
• 变量声明规范：所有函数和变量都要用const/let声明，避免全局污染，这是Node.js开发的基础规范。
• 注册顺序：服务模块在控制器中先注册，Fastify的register会在当前插件完成前初始化依赖插件，因此该写法是安全的。

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