Project Code Structure

The project code directory structure generated by sponge follows the Golang Standard Project Layout Specification.

Service Repository Type Description

Sponge supports three common code repository organization methods:

• Monolithic Application Monolithic Repository (monolith)
• Microservices Multi-Repository (multi-repo)
• Microservices Monolithic Repository (mono-repo)

For the differences and applicable scenarios of these three types, please refer to the Code Repository chapter.

Monolithic Repository, Microservices Multi-Repository Directory Structure

The following is the standard directory structure for Monolithic Application Monolithic Repository or Microservices Multi-Repository generated by sponge:

.
├── api            # Directory for protobuf files and generated *pb.go
├── assets         # Directory for other assets used with the resource library (images, logos, etc.)
├── cmd            # Program entry directory
├── configs        # Directory for configuration files
├── deployments    # Directory for bare metal, docker, k8s deployment scripts
├── docs           # Directory for design documents and interface documents
├── internal       # Directory for project internal code
│    ├── cache        # Business-based cache directory
│    ├── config       # Go struct configuration directory
│    ├── dao          # Data access directory
│    ├── database     # Database directory
│    ├── ecode        # Custom business error code directory
│    ├── handler      # HTTP business logic implementation directory
│    ├── model        # Database model directory
│    ├── routers      # HTTP router directory
│    ├── rpcclient    # gRPC client directory for connecting to gRPC services
│    ├── server       # Service entry, including http, gRPC, etc.
│    ├── service      # gRPC business logic implementation directory
│    └── types        # HTTP request and response types directory
├── pkg            # Directory for libraries that can be used by external applications
├── scripts        # Scripts directory
├── test           # Extra external test programs and test data
├── third_party    # Directory for dependent third-party protobuf files or other tools
├── Makefile       # Collection of development, test, deployment related commands
├── go.mod         # Go module dependencies and version control file
└── go.sum         # Go module dependency keys and checksum file

Web Service vs gRPC Service

• Web Service specific directories: internal/routers, internal/handler, internal/types
• gRPC Service specific directory: internal/service
• The rest of the directory structure is basically the same

Microservices Monolithic Repository Directory Structure

The directory structure for Microservices Monolithic Repository (mono-repo) generated by sponge is as follows:

.
├── api
│    ├── server1       # Directory for Service 1's protobuf files and generated *pb.go
│    ├── server2       # Directory for Service 2's protobuf files and generated *pb.go
│    ├── server3       # Directory for Service 3's protobuf files and generated *pb.go
│    └── ...
├── server1        # Code directory for Service 1, basically the same as the Microservices Multi-Repository (multi-repo) structure
├── server2        # Code directory for Service 2, basically the same as the Microservices Multi-Repository (multi-repo) structure
├── server3        # Code directory for Service 3, basically the same as the Microservices Multi-Repository (multi-repo) structure
├── ...
├── third_party    # Dependent third-party protobuf files
├── go.mod         # Go module dependencies and version control file
└── go.sum         # Go module dependency keys and checksum file

Tips

The names of subdirectories like server1, server2, server3, etc., are dynamically determined based on actual generation parameters. The internal structure of each subdirectory is consistent with the monolithic repository.

Code Layering Architecture

Layered Directory Description

The service code created by sponge adopts a layered architecture, with the responsibilities of each layer as follows:

1. Entry Layer (cmd/user/main.go)

   • Service startup entry
   • Responsible for initializing configurations, logs, and other infrastructure
   • Calls the server layer to start the HTTP service

2. Server Layer (internal/server)

   • Initializes the HTTP server
   • Initializes the gRPC server

3. Router Layer (internal/routers)

   • Defines the mapping between API endpoints and handlers
   • Implements route grouping and version control
   • Registers middleware to specific routes

4. Handler Layer

   • For HTTP services (internal/handler)
     • Handles HTTP requests and responses
     • Parameter validation and simple logic processing
     • Calls lower layers to get/process data
   • For gRPC services (internal/service)
     • Handles gRPC requests and responses
     • Parameter validation and simple logic processing
     • Calls lower layers to get/process data

5. Data Access Layer (internal/dao)

   • Database operation encapsulation
   • Implements basic CRUD operations
   • May include simple caching logic

6. Model Layer (internal/model)

   • Defines data structures
   • Includes database table mapping structs

Extended Layering Architecture

To implement more complex business scenarios, for different service types, it is recommended to add a business logic layer (internal/biz) above the data access layer (DAO):

• Web Service: Located between handler and DAO
• gRPC Service: Located between service and DAO
• Hybrid Service (gRPC+HTTP): Located between service and DAO

The advantages of this modification include:

1. Separation of Concerns:

   • handler focuses on HTTP protocol processing
   • service focuses on gRPC protocol processing
   • biz layer implements core business logic
   • dao layer is only responsible for data storage and retrieval

2. Code Reusability:

   • The business logic layer (biz) can be reused by multiple handler or service layers
   • Facilitates the implementation of Domain-Driven Design (DDD)

3. Testing Convenience:

   • Business logic can be tested independently
   • Does not depend on HTTP or gRPC frameworks

This layered architecture better adheres to the Single Responsibility Principle and can better handle increasing business complexity.