Node.js 实战一：构建你的第一套 Node.js 服务架构

你可能已经写过不少 API，但每次新开项目，还是会陷入：

“这次到底用 Express 还是 Koa？”

“这路由怎么写才不会越来越乱？”

“中间件、服务层、控制器到底要不要分？”

本篇文章不讲“Hello World”，而是带你一步步构建一个结构清晰、可扩展、适合团队协作的 Node.js 服务项目。

一、框架选择：Koa vs Express

Express：

• 上手简单，生态庞大

• 自带 middleware 系统 + 路由机制

• 老牌框架，稳定性好，文档丰富

Koa：

• 更轻量、更现代（由 Express 团队重写）

• 默认没有路由/中间件，需自行组合

• 使用 async/await 中间件更优雅（原生支持）

选型建议：

适合场景	推荐框架
快速搭建、文档多、团队协作小	Express
注重极致控制、自定义能力强、团队经验成熟	Koa

我们后续以 Koa 为例展开，但 Express 的结构也通用。

二、推荐项目结构（适用于 Koa / Express）

my-service/
├── src/
│   ├── controllers/     # 控制器层：处理路由逻辑
│   ├── services/        # 服务层：处理业务逻辑
│   ├── routes/          # 路由定义
│   ├── middlewares/     # 中间件（鉴权、日志等）
│   ├── utils/           # 工具函数
│   ├── config/          # 配置文件
│   ├── app.js           # 初始化入口
│   └── server.js        # 启动服务
├── tests/               # 单元/接口测试
├── .env                 # 环境变量
├── package.json
└── README.md

三、快速初始化一个 Koa 项目（含路由中间件结构）

安装依赖

npm install koa koa-router koa-bodyparser dotenv

app.js（应用初始化）

const Koa = require('koa');
const bodyParser = require('koa-bodyparser');
const registerRoutes = require('./routes');
require('dotenv').config();

const app = new Koa();

// 中间件
app.use(bodyParser());

// 注册路由
registerRoutes(app);

module.exports = app;

server.js（服务启动）

const app = require('./app');

const PORT = process.env.PORT || 3000;

app.listen(PORT, () => {
  console.log(` Server running at http://localhost:${PORT}`);
});

routes/index.js（注册路由）

const Router = require('koa-router');
const userRoutes = require('./user');

module.exports = (app) => {
  const router = new Router({ prefix: '/api' });
  router.use(userRoutes.routes());
  app.use(router.routes()).use(router.allowedMethods());
};

controllers/userController.js

exports.getProfile = async (ctx) => {
  ctx.body = { id: 1, name: 'Node Dev' };
};

routes/user.js

const Router = require('koa-router');
const { getProfile } = require('../controllers/userController');

const router = new Router({ prefix: '/user' });

router.get('/profile', getProfile);

module.exports = router;

四、进阶建议：为团队准备好这些基础设施

• 日志：接入 winston / pino

• 配置管理：dotenv + config 模块化方案

• 统一错误处理中间件

• 健康检查路由 /health

• 基础测试结构（Jest / Supertest）

总结

Node.js 服务的关键不是能不能跑，而是能不能“一直跑下去，还能方便别人接手”。

所以你要构建的，不是一个“项目”，而是一个“框架基础”。

• 用 Koa 或 Express 搭好结构

• 抽离路由 / 控制器 / 服务层

• 统一中间件、日志、配置

这才是从“写接口”走向“搭系统”的第一步。