技术的路上奔跑

入门

0%

从简单到复杂的软件工程结构

发表于 更新于 分类于 ， Valine：
本文字数： 5.1k 阅读时长 ≈ 5 分钟

一、前言

在后端软件工程中（当前文档以golang举例），从简单到复杂的项目结构设计需要根据功能需求、团队规模、可维护性和可扩展性进行分层抽象。以下是针对不同复杂度场景的目录结构和组织形式说明。

一、简单项目（单体应用）

适用于小型服务或原型开发，功能模块较少，无需复杂的分层。

典型目录结构

1
2
3
4
5
6
7
8
9
10
11
12
myapp/
├── main.go
├── go.mod
├── go.sum
├── handlers/
│   └── user_handler.go
├── models/
│   └── user.go
├── services/
│   └── user_service.go
└── config/
    └── config.go

组织形式特点

  1. 单入口点：main.go 作为程序入口，直接调用业务逻辑。
  2. 扁平化结构：直接通过包名划分逻辑，如 handlers（HTTP处理），models（数据模型），services（业务逻辑）。
  3. 依赖管理：使用 go.mod 管理依赖，直接通过相对路径导入模块。
  4. 简单配置：config/ 目录存放配置解析逻辑。

适用场景

  • 快速验证需求（如POC）
  • 单一功能模块（如简单的鉴权服务）

二、中等复杂项目（分层架构，服务拆分）

适用于需要分层设计的中型服务，可能包含多个功能模块（如认证、设备管理、策略引擎）。

典型目录结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
myapp/
├── go.mod
├── go.sum
├── cmd/
│   └── myapp/
│       └── main.go
├── internal/
│   ├── api/
│   │   ├── http/
│   │   │   └── user_api.go
│   │   └── grpc/
│   │       └── user_grpc.go
│   ├── service/
│   │   ├── user_service.go
│   │   └── auth_service.go
│   ├── repository/
│   │   ├── user_repo.go
│   │   └── db.go
│   ├── models/
│   │   └── user.go
│   └── config/
│       └── config.go
├── pkg/
│   ├── middleware/
│   │   └── jwt.go
│   └── utils/
│       └── logging.go
└── config/
    └── dev.yaml

组织形式特点

  1. 入口分层：
    • cmd/：区分不同运行入口（如 main.go 作为HTTP服务，grpc_main.go 作为gRPC服务）。
    • internal/：核心业务逻辑，仅允许同模块导入。
    • pkg/：公共工具类或第三方依赖封装。
  2. 分层设计：
    • API层：处理HTTP/gRPC请求的适配（如路由、中间件）。
    • Service层：业务逻辑，调用 Repository。
    • Repository层：数据访问逻辑（数据库、缓存、外部API）。
    • Model层：数据结构定义。
  3. 配置管理：
    • 使用 config/ 目录分离环境配置（如 dev.yaml, prod.yaml）。
  4. 中间件/工具封装：
    • pkg/middleware 放置安全中间件（如JWT、权限校验）。
    • pkg/utils 放置通用工具（如日志、加密、文件操作）。

适用场景

  • 需要多接口支持（HTTP + gRPC）
  • 功能模块较多，但未拆分为独立服务
  • 需要统一安全中间件（如零信任中的身份认证）

三、复杂项目（微服务/模块化架构）

适用于大规模系统，涉及多个微服务、统一终端管理、零信任集成（如身份认证、设备健康检查、策略下发等）。

典型目录结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
myapp/
├── go.mod
├── go.sum
├── cmd/
│   ├── user-service/
│   │   └── main.go
│   ├── device-service/
│   │   └── main.go
│   └── auth-service/
│       └── main.go
├── internal/
│   ├── api/
│   │   ├── user/
│   │   │   └── user_api.go
│   │   └── common/
│   │       └── auth.go
│   ├── service/
│   │   ├── user/
│   │   │   └── user_service.go
│   │   ├── device/
│   │   │   └── device_service.go
│   │   └── auth/
│   │       └── auth_service.go
│   ├── repository/
│   │   ├── user/
│   │   │   └── user_repo.go
│   │   ├── device/
│   │   │   └── device_repo.go
│   │   └── common/
│   │       └── db.go
│   ├── models/
│   │   ├── user/
│   │   │   └── user.go
│   │   ├── device/
│   │   │   └── device_model.go
│   │   └── common/
│   │       └── policy.go
│   └── config/
│       └── config.go
├── pkg/
│   ├── utils/
│   │   └── crypto.go
│   └── grpc/
│       └── client.go
├── apps/
│   ├── user-app/
│   │   └── main.go
│   ├── device-app/
│   │   └── main.go
│   └── auth-app/
│       └── main.go
├── config/
│   ├── user-service.yaml
│   ├── device-service.yaml
│   └── auth-service.yaml
└── scripts/
    └── init_db.go

组织形式特点

  1. 微服务拆分：
    • cmd/ 按服务划分（如 user-service, device-service）。
    • internal/ 按业务逻辑拆分（如 user, device, auth）。
  2. 模块化设计：
    • Service层：每个服务独立逻辑（如设备健康检查服务、策略下发服务）。
    • Repository层：数据访问层抽象，支持多数据源（如MySQL、MongoDB、ETCD）。
    • Model层：共享模型通过 internal/models/common 统一定义。
  3. 配置管理：
    • 每个服务独立配置文件（user-service.yaml, device-service.yaml），支持环境参数切换。
  4. 统一终端管理：
    • device-service 负责终端注册、状态监控、安全策略同步。
    • internal/repository/device/ 可能包含设备状态数据库操作。
    • internal/service/device/ 实现设备心跳、合规性检查。
  5. 多层依赖控制：
    • internal 模块仅被 cmd 和 pkg 导入，避免外部依赖污染核心逻辑。
    • pkg 模块对 internal 进行抽象封装（如数据库连接池、GRPC客户端）。

适用场景

  • 多微服务协同
  • 高度可扩展的系统（如支持多种终端类型、安全协议）

四、高级架构（分布系统/中台化/云原生）

适用于分布式系统、云原生部署（如K8s）、统一终端服务集成到中台架构中。

典型目录结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
myapp/
├── go.mod
├── go.sum
├── cmd/
│   ├── api-gateway/
│   │   └── main.go
│   ├── auth-service/
│   │   └── main.go
│   ├── device-service/
│   │   └── main.go
│   └── policy-service/
│       └── main.go
├── internal/
│   ├── api/
│   │   ├── http/
│   │   │   └── api_handler.go
│   │   └── grpc/
│   │       └── policy_grpc.go
│   ├── service/
│   │   ├── auth/
│   │   │   └── auth_service.go
│   │   ├── device/
│   │   │   └── device_service.go
│   │   └── policy/
│   │       └── policy_service.go
│   ├── repository/
│   │   ├── auth/
│   │   │   └── auth_db.go
│   │   ├── device/
│   │   │   └── device_cache.go
│   │   └── policy/
│   │       └── policy_db.go
│   ├── models/
│   │   ├── auth/
│   │   │   └── auth_model.go
│   │   ├── device/
│   │   │   └── device_model.go
│   │   └── common/
│   │       └── policy.go
│   └── config/
│       └── config.go
├── pkg/
│   ├── middleware/
│   │   └── zero-trust-middleware.go
│   ├── utils/
│   │   └── crypto_utils.go
│   ├── grpc/
│   │   └── client_utils.go
│   └── log/
│       └── logger.go
├── tools/
│   ├── generate/
│   │   └── proto_gen.go
│   └── scripts/
│       └── deploy.sh
├── config/
│   ├── env/
│   │   ├── dev.yaml
│   │   └── prod.yaml
│   └── k8s/
│       └── deployment.yaml
└── docs/
    └── api-spec.md

组织形式特点

  1. 服务化架构：
    • 每个子模块独立部署（如认证、设备、策略服务）。
    • internal 模块被多个服务复用，但通过 pkg 封装成共享库。
  2. 云原生适配：
    • config/k8s/ 存放Kubernetes部署配置。
    • tools/scripts/ 支持自动化部署和CI/CD。
  3. 零信任专项：
    • middleware/zero-trust-middleware.go 实现动态策略校验、设备可信度评估。
    • service/policy/ 负责策略引擎（如RBAC、ABAC、动态策略下发）。
  4. 统一终端管理：
    • device-service 与 policy-service 通过GRPC通信，实现终端策略同步。
    • repository/device/ 可能对接设备管理平台（如IoT Hub、终端代理）。
  5. 中台化设计：
    • pkg/ 提供通用能力（如日志、加密、GRPC客户端）。
    • internal/models/common/ 定义统一终端数据模型（如设备指纹、健康状态）。

适用场景

  • 分布式系统（如零信任的多节点认证）
  • 云原生部署（K8s、Docker）
  • 多终端统一管理（如移动端、IoT设备、PC端）

五、关键设计原则

  1. 模块隔离：
    • internal 模块仅允许同模块导入，避免外部依赖污染。
    • pkg 模块提供对外接口，内部逻辑通过 internal 封装。
  2. 分层设计：
    • API层：处理协议适配（HTTP/gRPC）。
    • Service层：业务逻辑，调用 Repository。
    • Repository层：数据访问，解耦数据库实现。
  3. 统一终端管理：
    • 设备相关逻辑集中在 device-service，通过接口与策略服务通信。
    • 使用 models/device/ 统一设备数据结构（如设备ID、状态、安全属性）。
  4. 零信任集成：
    • 安全中间件（如JWT、设备指纹校验）放在 pkg/middleware/zero-trust。
    • 策略引擎逻辑在 policy-service，支持动态策略下发。
  5. 配置与环境分离：
    • 使用 config/env/ 管理不同环境的配置（如开发、测试、生产）。
    • 通过环境变量或配置中心（如Consul、etcd）动态加载配置。

六、工具与规范建议

  1. Go Modules：使用 go.mod 管理依赖，避免全局依赖污染。
  2. Go Generate：通过 tools/generate/proto_gen.go 生成GRPC代码。
  3. CI/CD：在 tools/scripts/ 中编写部署脚本，支持自动化测试。
  4. 文档化：在 docs/ 中维护API文档、架构图、安全策略说明。
  5. 测试策略：
    • internal/service/ 的单元测试直接调用 repository 的Mock。
    • cmd/ 的集成测试模拟真实请求。

七、总结

复杂度目录结构特点适用场景
简单单入口、扁平化快速原型、小型服务
中等分层设计、模块化多接口支持、中型系统
复杂微服务拆分、中台化零信任多模块、统一终端管理
高级云原生、工具链分布式系统、K8s部署

关键点：

  • 从简单到复杂，逐步引入分层和模块化，避免过度设计。
  • 零信任服务端需特别关注安全中间件和策略引擎的抽象。
  • 统一终端服务端需设计设备管理、状态同步、策略下发的独立模块。
  • 保持 internal 与 pkg 的清晰边界，便于维护和复用。