跳至主要內容

项目代码结构

Vison2025/5/14大约 5 分钟核心概念project-layout

sponge 生成的项目代码目录结构遵循 Golang 标准项目布局规范。

服务仓库类型说明

sponge 支持三种常见的代码仓库组织方式：

  • 单体应用单体仓库 (monolith)
  • 微服务多仓库 (multi-repo)
  • 微服务单体仓库 (mono-repo)

关于这三种类型的区别和适用场景，请参考 代码仓库章节。


单体仓库、微服务多仓库目录结构

以下是 sponge 生成的单体应用单体仓库或微服务多仓库的标准目录结构：

.
├── api            # protobuf 文件和生成的*pb.go 目录
├── assets         # 其他与资源库一起使用的资产(图片、logo 等)目录
├── cmd            # 程序入口目录
├── configs        # 配置文件的目录
├── deployments    # 裸机、docker、k8s 部署脚本目录
├── docs           # 设计文档和界面文档目录
├── internal       # 项目内部代码目录
│    ├── cache        # 基于业务包装的缓存目录
│    ├── config       # Go 结构的配置文件目录
│    ├── dao          # 数据访问目录
│    ├── database     # 数据库目录
│    ├── ecode        # 自定义业务错误代码目录
│    ├── handler      # http 的业务功能实现目录
│    ├── model        # 数据库模型目录
│    ├── routers      # http 路由目录
│    ├── rpcclient    # 连接 grpc 服务的客户端目录
│    ├── server       # 服务入口，包括 http、grpc 等
│    ├── service      # grpc 的业务功能实现目录
│    └── types        # http 的请求和响应类型目录
├── pkg            # 外部应用程序可以使用的库目录
├── scripts        # 执行脚本目录
├── test           # 额外的外部测试程序和测试数据
├── third_party    # 依赖第三方 protobuf 文件或其他工具的目录
├── Makefile       # 开发、测试、部署相关的命令集合
├── go.mod         # go 模块依赖关系和版本控制文件
└── go.sum         # go 模块依赖项的密钥和校验文件

Web 服务 vs gRPC 服务

  • Web 服务特有目录：internal/routers、internal/handler、internal/types
  • gRPC 服务特有目录：internal/service
  • 其余目录结构基本一致

微服务单体仓库目录结构

sponge 生成的微服务单体仓库(mono-repo)的目录结构如下：

.
├── api
│    ├── server1       # 服务1的 protobuf 文件和生成的*pb.go 目录
│    ├── server2       # 服务2的 protobuf 文件和生成的*pb.go 目录
│    ├── server3       # 服务3的 protobuf 文件和生成的*pb.go 目录
│    └── ...
├── server1        # 服务1的代码目录，与微服务多仓库(multi-repo)目录结构基本一样
├── server2        # 服务2的代码目录，与微服务多仓库(multi-repo)目录结构基本一样
├── server3        # 服务3的代码目录，与微服务多仓库(multi-repo)目录结构基本一样
├── ...
├── third_party    # 依赖的第三方 protobuf 文件
├── go.mod         # go 模块依赖关系和版本控制文件
└── go.sum         # go 模块依赖项的密钥和校验和文件

提示

其中 server1、server2、server3 等子目录名称根据实际生成参数动态确定，每个子目录内部结构与单体仓库保持一致。


代码分层架构

分层目录说明

sponge 创建的服务代码采用分层架构，各层职责如下：

  1. 入口层 (cmd/user/main.go)

    • 服务启动入口
    • 负责初始化配置、日志等基础设施
    • 调用 server 层启动 HTTP 服务

  2. 服务层 (internal/server)

    • 初始化 HTTP 服务器
    • 初始化 gRPC 服务器

  3. 路由层 (internal/routers)

    • 定义 API 端点与 handler 的映射关系
    • 实现路由分组和版本控制
    • 注册中间件到特定路由

  4. 处理层

    • 对于 HTTP 服务 (internal/handler)
      • 处理 HTTP 请求和响应
      • 参数校验和简单逻辑处理
      • 调用下层获取/处理数据
    • 对于 gRPC 服务 (internal/service)
      • 处理 gRPC 请求和响应
      • 参数校验和简单逻辑处理
      • 调用下层获取/处理数据

  5. 数据访问层 (internal/dao)

    • 数据库操作封装
    • 实现 CRUD 基础操作
    • 可能包含简单缓存逻辑

  6. 模型层 (internal/model)

    • 定义数据结构
    • 包含数据库表映射结构体

扩展分层架构

若要实现更复杂业务场景，针对不同服务类型，建议在数据访问层(DAO)之上增加业务逻辑层(internal/biz)：

  • Web 服务：位于 handler 与 DAO 之间
  • gRPC 服务：位于 service 与 DAO 之间
  • 混合服务(gRPC+HTTP)：位于 service 与 DAO 之间

这样修改后优势包括：

  1. 职责分离：

    • handler 专注于 HTTP 协议处理
    • servic 专注于 gRPC 协议处理
    • biz 层实现核心业务逻辑
    • dao 层只负责数据存取

  2. 代码复用：

    • 业务逻辑层 biz 可被多个 handler 层或 service 层复用
    • 便于实现领域驱动设计(DDD)

  3. 测试便利：

    • 业务逻辑可独立测试
    • 不依赖 HTTP 或 gRPC 框架

这种分层架构更符合单一职责原则，能更好地应对业务复杂度增长。


Copyright © 2025 Vison