Node.js / 系统课时

建立标准项目目录

建立标准项目目录

这一节为一个小型 Node.js 项目建立清晰的目录骨架,并让源码、配置、测试和静态资源各自有明确边界。完成后,你可以直接运行入口文件和测试脚本,也能用一个检查命令确认目录没有遗漏。

学习目标

  • 按职责划分 src、config、test 与 public,避免源码和运行资产混在一起。
  • 用可跨平台执行的 Node 命令创建项目骨架,并写出最小可运行入口与测试。
  • 通过 npm 脚本和目录检查命令验证项目结构是否完整。

用职责划分目录边界

小项目不需要一开始就拆出十几个目录,但四类内容最好从第一天分开:业务源码放 src,非敏感默认配置放 config,测试放 test,需要原样对外提供的静态文件才放 public。package.json 与 .vscode 保持在项目根目录。

Node.js 项目标准目录及职责关系

位置 放什么 不建议放什么
src/ 应用源码、入口、业务模块 测试文件、构建产物
config/ 可提交仓库的默认配置 密钥、令牌、生产密码
test/ 单元测试、集成测试 运行时代码
public/ 图片、robots.txt 等静态文件 Node 业务源码
根目录 package.json、.gitignore、.vscode/ 大量业务模块

如果项目没有静态文件,可以暂时不使用 public;如果配置全部来自环境变量,也可以让 config 只保存配置加载代码。目录要服务实际职责,不要为了“看起来专业”预建空的 controller、service、repository 多层结构。

在空目录中生成骨架

先进入一个空项目目录,初始化 npm,再用 Node 自己的文件系统 API 创建四个目录。这样不依赖 Bash 的 mkdir -p,在 Windows、macOS 和 Linux 的 VS Code 终端都能执行。

bash
npm init -y
node -e "const fs=require('fs'); ['src','config','test','public'].forEach(d=>fs.mkdirSync(d,{recursive:true}))"
node -e "console.log(require('fs').readdirSync('.').sort().join('\n'))"

预期结果在空目录中至少能看到下面五项;如果 VS Code 已创建 .vscode,列表还会多出该目录。

text
config
package.json
public
src
test

接着创建 .gitignore,至少排除依赖、环境变量文件和覆盖率输出。config 可以提交默认值,但真实密钥应通过 .env、系统环境变量或密钥服务注入,不能写进版本库。

text
node_modules/
.env
coverage/

写出最小入口与测试

创建 src/index.js。这里既导出 add 供测试引用,又只在文件被直接执行时打印结果,避免测试 require 模块时产生多余输出。

js
function add(a, b) {
  return a + b;
}

if (require.main === module) {
  console.log(add(2, 3));
}

module.exports = { add };

创建 test/add.test.js,使用 Node 内置的严格断言,不引入第三方测试框架。断言失败时进程会以非零状态退出,适合后续接入 CI。

js
const assert = require("node:assert/strict");
const { add } = require("../src/index.js");

assert.equal(add(2, 3), 5);
assert.equal(add(-1, 1), 0);

console.log("test-ok");

把 package.json 调整为下面的最小可运行版本。private: true 可以防止误把练习项目发布到 npm;start 与 test 明确指向刚建立的两个入口。

json
{
  "name": "node-project-skeleton",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "start": "node src/index.js",
    "test": "node test/add.test.js"
  }
}

运行两个脚本:

bash
npm start
npm test

预期结果至少包含下面两行;npm 还会显示脚本名称等额外信息。

text
5
test-ok

用检查命令验收目录

最后用一个不依赖第三方包的命令检查四个关键目录。任何一个目录缺失时都会抛出错误并返回非零退出码;全部存在时打印固定标记,适合以后放进初始化脚本或 CI 的快速检查步骤。

bash
node -e "const fs=require('fs'); for (const d of ['src','config','test','public']) { if (!fs.existsSync(d)) throw new Error('missing '+d); } console.log('skeleton-ok')"

预期输出:

text
skeleton-ok

项目变大后再按真实依赖拆分,例如把 src 细分为 routes、services 或 db。判断标准很简单:同一职责的文件已经难以快速定位时再拆;只有一两个文件时继续放在 src 根部,比提前制造多层空目录更容易维护。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

建立标准项目目录

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通