JavaScript / TypeScript / 系统课时

组织可维护的代码结构

组织可维护的代码结构

本篇介绍如何通过函数拆分、模块划分和命名约定组织 JavaScript 代码,让项目在需求变化和多人协作时仍然容易理解和修改。

学习目标

  • 理解拆分函数和模块的基本原则。
  • 掌握清晰命名和减少重复代码的方法。
  • 能够设计简单、可维护的 JavaScript 文件结构。

为什么需要代码结构设计

小规模脚本通常可以把所有代码写在一个文件中,但随着功能增加,代码之间的依赖会快速变复杂。良好的结构可以降低修改成本,让开发者更容易定位功能和修复问题。

可维护代码通常具有以下特点:

  • 一个函数只负责一个明确任务。
  • 模块之间通过清晰接口协作。
  • 变量和函数名称能够表达用途。
  • 相同逻辑不会重复出现在多个位置。

拆分函数降低复杂度

函数拆分的核心不是让函数数量变多,而是让每个函数拥有明确职责。

例如,一个处理用户注册的函数不应该同时负责验证、保存数据和发送通知。

js
function validateUser(user) {
  return user.name && user.email;
}

function saveUser(user) {
  console.log(`save ${user.email}`);
}

function registerUser(user) {
  if (!validateUser(user)) {
    throw new Error('invalid user');
  }

  saveUser(user);
}

registerUser({ name: 'Tom', email: 'tom@example.com' });

预期输出

text
save tom@example.com

拆分后,每个函数都可以单独测试,也方便未来替换实现。

使用模块划分代码

当功能增长到多个文件时,可以使用 ES Module 将相关代码组织在一起。

片段示例:以下代码依赖支持 ES Module 的运行环境。

js
// user.js
export function createUser(name) {
  return { name };
}

// app.js
import { createUser } from './user.js';

const user = createUser('Tom');
console.log(user.name);

预期结果

text
Tom

模块划分时,应按照功能职责组织文件,而不是简单按照文件大小拆分。

建立清晰命名约定

名称是代码的重要说明。好的命名可以减少额外注释。

类型 推荐方式 示例
函数 动词描述行为 calculateTotal
变量 表达数据含义 userCount
布尔值 使用状态含义 isLoggedIn
常量 表达固定配置 MAX_RETRY_COUNT

避免使用 data、temp、handle 这类无法表达具体含义的名称。

减少重复代码

重复代码会导致多个位置同时维护同一逻辑。发现重复时,可以提取公共函数或模块。

例如多个地方都需要格式化日期,就应该集中处理:

js
function formatDate(date) {
  return new Intl.DateTimeFormat('zh-CN').format(date);
}

console.log(formatDate(new Date('2026-01-01')));

预期输出

text
2026/1/1

提取公共逻辑后,未来修改格式时只需要调整一个位置。

什么时候不应该拆分

过度拆分同样会降低可读性。一个只有几行且只被使用一次的简单逻辑,不一定需要独立成模块。

判断是否拆分时,可以关注三个问题:

  • 这个逻辑是否有独立职责。
  • 这个逻辑是否可能被复用。
  • 修改这个逻辑时是否希望只影响一个位置。

可维护结构的目标不是文件更多或函数更多,而是让代码关系清晰,让变化发生时能够快速、安全地修改。

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

目录与阅读设置

阅读设置

17

记录一个想法

组织可维护的代码结构

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

登录哪都通