HelloWorld 结构设计教程

用最小可运行单元建立清晰分层、模块化的HelloWorld项目：入口、配置、业务、接口与测试各司其职；用约定胜于配置的目录与接口定义，配合自动化构建与文档，能保证可扩展、可维护和易测试。同时保持轻量和可理解的代码，便于新人上手、快速迭代与跨团队协作。从架构、目录、接口到测试都有可复用模板。且易落地。

什么是“HelloWorld 结构设计”

把“HelloWorld”不只是当作一句输出，而是把它当成一个微型项目来设计：把程序拆成若干明确的部分（入口、配置、业务逻辑、接口、测试、文档），使每一部分都能独立理解、修改与验证。这样做的好处是在学会最小示例的同时，掌握可复制到真实项目的架构思路。

用费曼法则解释一遍

费曼写作法的核心是把复杂概念讲成简单的话。想象你要教一个刚学编程的朋友：你会先让他运行程序，然后逐步解释“哪里是入口”“业务逻辑放哪儿”“为什么要做测试”。通过这样“由浅入深”的讲解，你能把抽象的架构转成可操作的步骤。

设计原则（短小但有用）

• 单一职责：每个文件/模块只做一件事；HelloWorld 的“输出”与配置不混在一起。
• 分层清晰：入口 → 配置 → 业务 → 接口/适配器 → 测试。
• 可读优先于聪明：别用花哨技巧换可读性，尤其是示例代码里。
• 约定优于配置：统一目录与命名，使新人能快速上手。
• 自动化最低线：至少有一个能跑的测试和一个能复现构建的命令。

推荐的目录结构

下面给出一个通用、轻量且可跨语言借鉴的目录结构（这是我在教新人的时候常用的模板）：

hello-world/
├─ README.md
├─ src/
│  ├─ main.(js|py|go|java)
│  ├─ config/
│  ├─ service/
│  └─ adapter/
├─ tests/
├─ scripts/
└─ .ci/ (或 .github/workflows/)

说明：src/main 是程序入口，config 放运行时配置与默认值，service 放业务逻辑，adapter 放和外部交互的代码（stdin/stdout、HTTP、文件等）。

一个更具体的文件列表

• README.md：如何运行、如何测试、设计要点
• src/main：启动脚本（最薄）
• src/service/hello.py（或 hello.js）：返回“HelloWorld”的函数
• tests/test_hello.py：对 service 的单元测试
• scripts/run.sh：一键运行

按语言分解：示例与理由

Node.js（最常见的教学语言）

做法是把启动仅当作调度器，业务函数放到独立模块，测试时直接导入业务模块，避免启动整个进程。

// src/main.js
const { sayHello } = require('./service/hello');
console.log(sayHello());

// src/service/hello.js
function sayHello(name = 'World') {
  return `Hello ${name}`;
}
module.exports = { sayHello };

这样单元测试可以直接 require(‘./service/hello’) 并断言返回值。

Python（教学与脚本偏好）

# src/main.py
from service.hello import say_hello

if __name__ == '__main__':
    print(say_hello())

# src/service/hello.py
def say_hello(name='World'):
    return f'Hello {name}'

Go（编译型示例）

Go 更适合把业务函数放在包里，main 包调用。编译与测试独立。

接口与测试策略

在HelloWorld项目里测试不需要复杂工具，但要体现层次化测试思想：

• 单元测试：验证业务函数的纯逻辑，速度要快。
• 集成测试：验证入口与业务如何协同，例如通过模拟输入检查输出。
• 端到端（可选）：直接运行脚本并检查 stdout（CI 中常用）。

测试示例（Pytest 风格）

# tests/test_hello.py
from service.hello import say_hello

def test_default():
    assert say_hello() == 'Hello World'

def test_name():
    assert say_hello('Alice') == 'Hello Alice'

自动化与文档（最低可交付标准）

把“怎么跑”“怎么测试”“设计要点”写进 README，是最直接的文档。再配一个最简单的 CI 配置，让每次提交都能跑测试。

• README：运行步骤、示例输出、设计决策
• Makefile 或 scripts/run.sh：一键运行与一键测试
• CI：只要能跑测试并返回绿灯即可

常见误区与权衡

做示例项目时容易犯一些毛病，提醒一下：

• 把业务逻辑写在入口文件里——这样很难单元测试。
• 过度工程化——HelloWorld 本来是教学用例，避免引入复杂依赖。
• 把配置硬编码——会影响示例的可移植性。

一个简单的权衡表

实战小贴士（那些年教新人的经验）

• 先做能跑的最小版本，再逐步拆分模块。别一开始就搞全家桶。
• 把测试写在业务函数完成前或同时完成，这样能保证设计的可测性。
• README 写成“上手指南”而不是长篇文档，三条命令能跑通最好。
• 用一致的命名约定，比如 service/* 放业务，adapter/* 放依赖、io 相关代码。

把HelloWorld扩展成课堂案例

当你要用 HelloWorld 做课堂示例时，可以按模块逐步引入新概念：先让学员实现 sayHello；再引入配置（命令行参数或环境变量）；再引入依赖注入或适配器；最后讲测试与 CI。每一步都只增加一层复杂度，这样学习成本最小。

如果你现在要动手做一个示例项目，先复制上面的目录结构，写一个最薄的 main 和一个返回字符串的函数，接着加一个简单测试，最后把运行与测试命令写到 README。按这个节奏，你会发现从“会跑一个HelloWorld”到“能交付可测试、可复用的示例”其实并不遥远。