I. What Is a Module?
A module is a unit of code organization provided by a programming language or runtime environment. It groups related variables, functions, types, and other definitions together and exposes functionality to the outside through a well-defined interface.
For example, a user management system might contain:
- User registration.
- User login.
- User information queries.
- User information modification.
- User permission management.
If all code is placed in a single file, it becomes increasingly difficult to maintain as the business grows.
It can be split into multiple modules by function:
user/
├── register
├── login
├── profile
└── permission
Each module is responsible for a relatively independent function and collaborates with other modules through interfaces.
1.1 Core Roles of Modules
Modules mainly address the following problems:
1. Code Organization
Manage related code centrally and prevent all functionality from being mixed together.
2. Naming Isolation
Different modules can have variables, functions, or types with the same name, reducing naming conflicts.
3. Implementation Encapsulation
A module can expose only the necessary interfaces and hide internal implementation details.
4. Code Reuse
A module can be imported and called by multiple programs or other modules.
5. Dependency Management
Clarify the reference relationships between modules, making it easier to maintain the program structure.
6. Independent Development
Different developers can develop and test in parallel around module boundaries.
1.2 Basic Composition of a Module
A typical module may contain the following:
| Component | Description |
|---|---|
| Module name | A unique name or path that identifies the module |
| Variables | Data definitions inside the module |
| Functions | Functionality provided by the module |
| Types | Classes, structs, interfaces, enums, etc. |
| Constants | Fixed values defined inside the module or exposed externally |
| Exported interfaces | Members that external code is allowed to access |
| Internal implementation | Implementation details not exposed externally |
| Dependency declarations | Other modules that the module needs to use |
The structure of a module is not determined entirely by the number of files.
In different languages, a module may correspond to a source file, a folder, a compilation unit, or a code object dynamically created by the runtime.
II. What Is a Package?
A package is usually a higher-level structure used to organize multiple modules, manage namespaces, and provide code distribution capabilities.
For example, a network communication library might contain:
network/
├── http
├── websocket
├── tcp
├── udp
└── dns
Here, network can serve as a package containing multiple functional modules.
Packages are typically used to:
- Organize related modules.
- Establish namespace hierarchies.
- Manage public interfaces.
- Distribute reusable code.
- Declare external dependencies.
- Manage versions.
- Form independent software components.
2.1 Relationship Between Modules and Packages
In many languages, a module can be understood as the basic unit of code organization, and a package as a container that organizes multiple modules.
flowchart TD
A["Application"] --> B["Business Package"]
A --> C["Infrastructure Package"]
B --> D["User Module"]
B --> E["Order Module"]
B --> F["Payment Module"]
C --> G["Database Module"]
C --> H["Cache Module"]
C --> I["Logging Module"]
style A fill:#FFF5DE,stroke:#E8D29A,color:#334155
style B fill:#E5F4EC,stroke:#A3CBB5,color:#334155
style C fill:#E5F4EC,stroke:#A3CBB5,color:#334155
style D fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style E fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style F fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style G fill:#F3EDFC,stroke:#C4B2E3,color:#334155
style H fill:#F3EDFC,stroke:#C4B2E3,color:#334155
style I fill:#F3EDFC,stroke:#C4B2E3,color:#334155
linkStyle default stroke:#A3B8AC,stroke-width:1.5px
However, it must be noted: there is no unified hierarchical relationship between modules and packages that applies to all programming languages.
Definitions vary greatly across languages:
- Python: A module usually corresponds to a
.pyfile, and a package is usually used to organize multiple modules. - Java: Packages are mainly used for namespaces and type organization, and the compilation unit is usually a source file.
- Go: A package is an important unit of source code organization, compilation, and access control; a package usually consists of multiple source files in the same directory.
- Rust: Modules are used to organize code hierarchy, a Crate is the compilation unit, and a Cargo Package is the unit of project and distribution management.
- JavaScript: An ES Module usually uses a file as a module, and an npm Package is the unit of publishing and dependency management.
- C/C++: Code is usually organized using header files, source files, namespaces, libraries, and build systems; there is no fully corresponding general system of modules and packages.
Therefore, when learning a specific language, it is necessary to distinguish between modules, packages, namespaces, compilation units, and software distribution units.
III. Core Concepts of Modules and Packages
3.1 Namespace
A namespace is used to organize names and avoid conflicts between identifiers in different code regions.
For example:
# user.py
name = "User Module"
def get_name():
return name
# order.py
name = "Order Module"
def get_name():
return name
Both modules define name and get_name, but they are in different module namespaces.
When calling:
import user
import order
print(user.get_name())
print(order.get_name())
Output:
User Module
Order Module
The module name is equivalent to the namespace prefix used when accessing members.
Namespaces can adopt a hierarchical structure:
company
├── user
│ ├── account
│ └── permission
└── order
├── payment
└── delivery
For example:
company.user.account
company.order.payment
This structure can reduce the risk of name conflicts in large projects.
Note that a namespace does not necessarily imply a separate runtime memory space. It is first and foremost a mechanism for organizing and resolving names.
3.2 Import
Importing is the mechanism that brings definitions provided by other modules into the current code environment.
For example, in Python:
import math
result = math.sqrt(16)
print(result)
Here, the math module is brought in via import, and then its members are accessed.
Common import styles:
# Import the entire module
import math
# Use an alias
import math as m
# Import specific members
from math import sqrt
# Import multiple members
from math import sqrt, pow
Different languages use different import syntax:
| Language | Import Mechanism |
|---|---|
| Python | import, from...import |
| Java | import |
| JavaScript | import |
| TypeScript | import |
| Go | import |
| Rust | use, mod |
| C | #include |
| C++ | #include, import (module mechanism) |
Note that #include in C/C++ is a preprocessing directive and is not exactly the same as the runtime or language-level module import mechanisms of languages such as Python and JavaScript.
3.3 Export
Exporting is the mechanism by which a module exposes variables, functions, types, or other members to the outside.
For example, JavaScript:
// math.js
export function add(a, b) {
return a + b;
}
export const PI = 3.14159;
Other modules can import them:
// main.js
import { add, PI } from "./math.js";
console.log(add(10, 20));
console.log(PI);
Exports can be divided into:
- Named exports (Named Export).
- Default exports (Default Export).
- Public types or interfaces.
- Public functions and constants.
Export mechanisms differ across languages.
For example:
- Java controls the accessibility of classes and members through access modifiers.
- Go controls cross-package visibility through the capitalization of the first letter of identifiers.
- Rust uses
pubto control public visibility. - Python generally manages member access through naming conventions and module attributes, and has no enforced universal private member access control mechanism.
- C/C++ generally manages interfaces through header files, linking, and language access control mechanisms.
3.4 Access Control
Modules and packages are not only used to organize code; they also need to control which members can be accessed externally.
Common access levels:
| Access level | Typical meaning |
|---|---|
| Public | Exposed externally |
| Private | Accessible only within a specific type or scope |
| Protected | Allows access through specific inheritance relationships |
| Internal | Accessible within a specified assembly or module scope |
| Package-private | Accessible within package scope |
Different languages do not define these levels in exactly the same way.
For example, Java:
package com.example.user;
public class User {
public String name;
private String password;
protected int age;
void internalMethod() {
// Default package-level access
}
}
Here:
public: can be accessed by other packages.private: can only be accessed within the current class.protected: allows access within the same package, and also allows access by subclasses that meet inheritance rules.- No access modifier: has package-level access.
Access control helps hide internal implementation and reduce external code's dependence on module internals.
IV. Modular Design (Modularization)
Modularization is the process of splitting a complex system into multiple relatively independent modules with clear responsibilities.
Modularization is not just splitting code into multiple files; it is about establishing reasonable functional boundaries and dependency relationships.
4.1 Why Is Modularization Needed?
Suppose a system includes businesses such as users, orders, payments, and inventory.
If all logic is written in a single file:
application.py
The following problems may arise:
- The code file becomes too large.
- Different business logic is mixed together.
- Modifying one feature affects other features.
- Code is difficult to reuse.
- The testing scope is difficult to control.
- Conflicts easily occur during multi-person collaboration.
After modularization:
application/
├── user/
│ ├── service.py
│ └── repository.py
├── order/
│ ├── service.py
│ └── repository.py
├── payment/
│ ├── service.py
│ └── gateway.py
└── inventory/
├── service.py
└── repository.py
Each module organizes code around relatively clear business responsibilities.
4.2 High Cohesion and Low Coupling
Important goals of modular design are high cohesion and low coupling.
High cohesion: The functions within a module are organized around the same clear responsibility, and members have a strong business relationship with one another.
Low coupling: Minimize unnecessary dependencies between modules to reduce the impact of changes in one module on other modules.
For example:
The user module is responsible for user information management, the order module for order business, and the payment module for payment processing.
flowchart TD
A["Application Entry"] --> B["Order Module"]
B --> C["User Module"]
B --> D["Payment Module"]
B --> E["Inventory Module"]
D --> F["Payment Interface"]
E --> G["Inventory Interface"]
style A fill:#FFF5DE,stroke:#E8D29A,color:#334155
style B fill:#E5F4EC,stroke:#A3CBB5,color:#334155
style C fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style D fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style E fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style F fill:#F3EDFC,stroke:#C4B2E3,color:#334155
style G fill:#F3EDFC,stroke:#C4B2E3,color:#334155
linkStyle default stroke:#A3B8AC,stroke-width:1.5px
The key here is not the number of modules, but whether the module boundaries are reasonable.
If modules are split too little, it is easy to end up with large modules with confused responsibilities; if split too much, the cost of inter-module communication and dependency management may increase.
4.3 Module Boundaries and Interface Design
Modules usually collaborate through interfaces.
For example, the order module should not depend directly on all the internal implementations of the payment module; instead, it should depend on the stable interface provided by the payment module.
This can be abstracted as:
Order Module
|
| Call payment interface
|
Payment Interface
|
| Concrete implementation
|
Payment Service
Interface design needs to focus on:
- Input parameters.
- Return results.
- Error handling.
- Data structures.
- Permission boundaries.
- Compatibility.
- Version changes.
A good module interface should be as stable as possible, while the internal implementation can evolve independently.
V. Module Dependencies and Dependency Relationships
Modules are usually not completely independent; they form dependencies through imports, calls, and interfaces.
5.1 What Is a Module Dependency?
A module dependency means that a module needs to use the capabilities provided by another module when compiling, running, or executing a certain function.
For example:
# order.py
from payment import process_payment
def create_order():
process_payment()
Here the order module depends on the payment module.
Dependencies can form a directed graph:
flowchart TD
A["Application Entry"] --> B["Order Module"]
B --> C["User Module"]
B --> D["Payment Module"]
D --> E["Payment Gateway"]
B --> F["Inventory Module"]
style A fill:#FFF5DE,stroke:#E8D29A,color:#334155
style B fill:#E5F4EC,stroke:#A3CBB5,color:#334155
style C fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style D fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style E fill:#F3EDFC,stroke:#C4B2E3,color:#334155
style F fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
linkStyle default stroke:#A3B8AC,stroke-width:1.5px
5.2 Direct and Transitive Dependencies
Direct Dependency
Module A directly references module B.
For example:
A → B
Transitive Dependency
Module A depends on B, and B in turn depends on C, so in some cases A indirectly depends on C.
A → B → C
Transitive dependencies are very common in large projects.
They can cause the following problems:
- Dependency version conflicts.
- Unnecessary dependency propagation.
- Propagation of security vulnerabilities.
- Increased build size.
- Compatibility issues during upgrades.
Therefore, dependency management must focus not only on the modules you directly introduce, but also on the complete dependency tree.
5.3 Circular Dependency
A circular dependency means that multiple modules form a closed loop of dependencies.
For example:
A → B
B → C
C → A
This structure increases the complexity of module initialization, compilation, and maintenance.
flowchart TD
A["Module A"] --> B["Module B"]
B --> C["Module C"]
C --> A
style A fill:#F3EDFC,stroke:#C4B2E3,color:#334155
style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style C fill:#E5F4EC,stroke:#A3CBB5,color:#334155
linkStyle default stroke:#A3B8AC,stroke-width:1.5px
Circular dependencies can lead to:
- An uncertain order of module initialization.
- Some modules being accessed before they have finished initializing.
- Compile-time dependencies that are difficult to resolve.
- Difficulty in testing and refactoring.
- Blurred boundaries of module responsibilities.
Different languages handle circular dependencies in different ways:
| Language | Typical behavior |
|---|---|
| Python | May encounter issues where partially initialized modules are accessed |
| JavaScript | ES Modules support circular references, but may encounter issues such as the temporal dead zone |
| Java | Classes can reference each other, but initialization and design still require care |
| Go | Circular imports cannot be formed within the same package |
| Rust | Module paths can reference each other, but type definitions and dependency relationships are still constrained by compilation rules |
| C/C++ | Mutual inclusion of header files may cause declaration dependency and compilation issues |
5.4 How to Resolve Circular Dependencies?
Common solutions:
1. Extract Common Modules
Extract functionality that multiple modules depend on into an independent module.
A → Common
B → Common
C → Common
2. Introduce Interfaces or Abstraction Layers
Modules depend on interfaces rather than directly on concrete implementations.
3. Adjust Responsibility Boundaries
Re-analyze module responsibilities to avoid two modules taking on each other's business logic.
4. Use Dependency Injection
External containers or callers provide dependency objects, reducing direct creation and references between modules.
5. Decouple via Events or Messages
Use event notifications or messaging mechanisms to avoid direct call relationships between modules.
6. Package Management
Package management refers to the mechanism for managing the acquisition, installation, upgrade, uninstallation, version constraints, and dependency resolution of software packages.
Modern software development usually uses a large number of third-party libraries and rarely relies entirely on the standard library to implement all functionality.
For example:
- Python uses the PyPI ecosystem and pip.
- JavaScript uses npm, pnpm, and Yarn.
- Java uses Maven and Gradle.
- Go uses Go Modules.
- Rust uses Cargo.
- PHP uses Composer.
- .NET uses NuGet.
6.1 What Is a Software Package?
A software package is usually a software unit that can be distributed, installed, and reused.
It may contain:
- Source code.
- Compiled binary files.
- Modules or libraries.
- Metadata.
- Version information.
- Dependency declarations.
- Configuration files.
- Documentation.
A software package is not necessarily equivalent to a module in a programming language.
For example, an npm package can contain multiple JavaScript modules; a Python distribution can also contain multiple Python packages and modules.
Therefore, it is necessary to distinguish between:
- Source code modules.
- Language packages.
- Software distribution packages.
- Dependency management units.
6.2 Package Manager
A package manager is a tool used to automate software package management.
Typical responsibilities include:
- Locate software packages.
- Download software packages.
- Install software packages.
- Resolve dependencies.
- Check version compatibility.
- Upgrade and uninstall software packages.
- Manage the local dependency environment.
- Verify package integrity.
Typical workflow:
flowchart TD
A["Declare project dependencies"] --> B["Package manager reads configuration"]
B --> C["Resolve dependencies"]
C --> D["Check version constraints"]
D --> E["Download packages"]
E --> F["Install dependencies"]
F --> G["Generate or update lockfile"]
G --> H["Build or run project"]
style A fill:#E5F4EC,stroke:#A3CBB5,color:#334155
style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style C fill:#F3EDFC,stroke:#C4B2E3,color:#334155
style D fill:#FFF5DE,stroke:#E8D29A,color:#334155
style E fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style F fill:#E5F4EC,stroke:#A3CBB5,color:#334155
style G fill:#F3EDFC,stroke:#C4B2E3,color:#334155
style H fill:#E8EDF2,stroke:#B8C3CE,color:#334155
linkStyle default stroke:#A3B8AC,stroke-width:1.5px
6.3 Package Registry
A package registry is a service used to store and distribute software packages.
Common public registries:
| Ecosystem | Primary Registry |
|---|---|
| Python | PyPI |
| JavaScript | npm Registry |
| Java | Maven Central |
| Go | Go Module Proxy |
| Rust | crates.io |
| PHP | Packagist |
| .NET | NuGet Gallery |
Package managers typically fetch packages through a registry and install them into the local environment or the project's dependency directory.
Note that public registries are not the only source for all dependencies. Enterprise projects may also use private registries, mirror registries, or internal artifact repositories.
VII. Dependency Versioning
Packages usually carry version numbers, and a project uses version constraints to determine which versions may be used.
7.1 Semantic Versioning
Semantic Versioning (SemVer) is a common version numbering specification.
Typical format:
MAJOR.MINOR.PATCH
For example:
2.5.3
Meaning of each part:
| Version Part | Meaning | Common Changes |
|---|---|---|
| MAJOR | Major version number | Incompatible API changes |
| MINOR | Minor version number | New backward-compatible features |
| PATCH | Patch version number | Backward-compatible bug fixes |
For example:
2.5.3: the current version.2.6.0: adds new backward-compatible features.2.5.4: fixes a bug.3.0.0: may contain incompatible API changes.
Semantic Versioning is a convention, and it does not mean every package follows it strictly.
7.2 Version Constraints
Projects usually do not declare only a single fixed version; instead, they use version constraints to express the allowed version range.
For example:
{
"dependencies": {
"express": "^4.18.0",
"lodash": "~4.17.0"
}
}
Under the common npm semantic versioning rules:
^4.18.0: allows compatible 4.x versions, but does not move to 5.0.0.~4.17.0: allows patch versions of 4.17.x, but does not move to 4.18.0.
Note that different package managers and version constraint syntaxes are not entirely the same, and npm's rules cannot be applied directly to every ecosystem.
7.3 Lockfile
A lockfile records the exact resolved versions of dependencies and related information.
Common files:
| Ecosystem | Lockfile |
|---|---|
| npm | package-lock.json |
| pnpm | pnpm-lock.yaml |
| Yarn | yarn.lock |
| Python | Depends on the tool, for example Poetry's poetry.lock |
| Rust | Cargo.lock |
| Go | go.sum records module content checksums, while go.mod declares module dependencies |
| PHP | composer.lock |
| .NET | packages.lock.json (when the lockfile mechanism is enabled) |
The main value of a lockfile:
- Pins the dependency resolution result.
- Improves consistency across team development environments.
- Reduces the uncertainty introduced by dependency upgrades.
- Improves the reproducibility of the build process.
It is important to distinguish dependency declaration files from lockfiles; their responsibilities are not entirely the same.
For example, Go's go.mod is used to declare the module path and dependency versions, while go.sum is used to record checksums of module content; it is not a complete dependency lockfile in the simple sense.
VIII. Dependency Resolution and Dependency Conflicts
When a project depends on multiple packages, the package manager needs to compute a set of dependencies that satisfies the version constraints.
8.1 Dependency Tree
For example:
Application
├── Package A
│ └── Package C
└── Package B
└── Package C
The application directly depends on A and B, and both A and B depend on C.
In this case, C is a transitive dependency of the application.
The dependency tree may further expand into a complex dependency graph.
8.2 Version Conflicts
Suppose:
Package A → Library C 1.x
Package B → Library C 2.x