Creating a New Module

Relevant source files

The following files were used as context for generating this wiki page:

• pom.xml
• zheng-demo/pom.xml
• zheng-cms/pom.xml
• zheng-cms/zheng-cms-admin/pom.xml
• zheng-upms/pom.xml
• zheng-upms/zheng-upms-dao/pom.xml
• zheng-demo/zheng-demo-rpc-api/src/main/java/com/zheng/demo/rpc/api/DemoService.java
• zheng-cms/zheng-cms-web/pom.xml

The zheng project is a large-scale, distributed system built using a multi-module Maven structure. This architecture promotes separation of concerns, reusability, and independent development and deployment of different business functionalities. Creating a new module involves setting up a specific directory and Maven pom.xml configuration that aligns with the project's established patterns.

This guide outlines the standard procedure for creating a new top-level module, such as zheng-mynewmodule, by following the conventions established in existing modules like zheng-demo, zheng-cms, and zheng-upms. The process involves defining a parent POM for the new module, structuring it into standardized sub-modules (e.g., common, dao, rpc-api, rpc-service, web), and integrating it into the main project build.

Project Structure Overview

The zheng project is composed of several top-level modules, each representing a distinct functional area of the application. These are all aggregated in the root pom.xml file.

The following diagram illustrates the high-level module structure of the project.

This diagram shows the top-level modules declared in the root pom.xml.
Sources: pom.xml:25-36

Step 1: Create the Top-Level Module

First, create a new directory for your module at the root of the project (e.g., zheng-mynewmodule). Inside this directory, create a pom.xml file that will serve as the parent POM for all of its sub-modules.

Parent Module POM (zheng-mynewmodule/pom.xml)

This POM should have packaging set to pom and will define the sub-modules that constitute your new feature. It inherits from the main project pom.xml implicitly through the directory structure, but it's good practice to define its own groupId, artifactId, and version.

A typical top-level module POM contains a <modules> section listing its children. The zheng-demo module provides a clear template.

<!-- zheng-demo/pom.xml -->
<project ...>
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.zheng</groupId>
    <artifactId>zheng-demo</artifactId>
    <version>1.0.0</version>
    <packaging>pom</packaging>

    <name>zheng-demo</name>
    <url>http://www.zhangshuzheng.cn</url>

    ...

    <modules>
        <module>zheng-demo-rpc-api</module>
        <module>zheng-demo-rpc-service</module>
        <module>zheng-demo-web</module>
    </modules>
</project>

Sources: zheng-demo/pom.xml:1-29

Update Root POM

After creating your new module's directory and pom.xml, you must register it in the root pom.xml file by adding it to the <modules> list.

<!-- pom.xml -->
<modules>
    <module>zheng-admin</module>
    <module>zheng-common</module>
    ...
    <module>zheng-demo</module>
    <!-- Add your new module here -->
    <module>zheng-mynewmodule</module>
</modules>

Sources: pom.xml:25-37

Step 2: Define Sub-Module Structure

Within your new top-level module directory (zheng-mynewmodule/), create subdirectories for each of the standard sub-modules. The project follows a consistent pattern for separating concerns.

The following diagram shows the typical sub-module structure, using zheng-cms as an example.

This diagram illustrates the sub-modules within a top-level module and their typical dependencies.
Sources: zheng-cms/pom.xml:20-27, zheng-cms/zheng-cms-admin/pom.xml:20-24, zheng-upms/zheng-upms-dao/pom.xml:20-23

Standard Sub-Modules

Each sub-module has a specific purpose and its own pom.xml that declares its parent and dependencies.

Sub-Module Suffix	Purpose	Example POM
-common	Contains common models, constants, and utility classes shared across the module.	zheng-cms/zheng-cms-common/pom.xml
-dao	Data Access Object layer. Manages database interactions, often using MyBatis.	zheng-upms/zheng-upms-dao/pom.xml
-rpc-api	Defines the Remote Procedure Call (RPC) service interfaces. This is a lightweight JAR shared with clients.	zheng-demo/pom.xml (references zheng-demo-rpc-api)
-rpc-service	The server-side implementation of the RPC interfaces defined in the -rpc-api module.	zheng-cms/zheng-cms-rpc-service/pom.xml
-web	A user-facing web application (WAR).	zheng-cms/zheng-cms-web/pom.xml
-admin	An administration-facing web application (WAR), often secured by zheng-upms-client.	zheng-cms/zheng-cms-admin/pom.xml
-job	Contains scheduled tasks or background jobs.	zheng-cms/zheng-cms-job/pom.xml

Sub-Module POM Configuration

Each sub-module's pom.xml must define its parent, which is the top-level module POM you created in Step 1.

Example: zheng-mynewmodule-admin/pom.xml

This example shows a web-based admin sub-module. It packages as a war, specifies its parent, and declares dependencies on the module's own rpc-api and the centralized zheng-upms-client for security.

<project ...>
    <parent>
        <groupId>com.zheng</groupId>
        <artifactId>zheng-mynewmodule</artifactId> <!-- Parent is the new top-level module -->
        <version>1.0.0</version>
    </parent>

    <artifactId>zheng-mynewmodule-admin</artifactId>
    <packaging>war</packaging>

    <dependencies>
        <!-- Dependency on the module's own API -->
        <dependency>
            <groupId>com.zheng</groupId>
            <artifactId>zheng-mynewmodule-rpc-api</artifactId>
            <version>1.0.0</version>
        </dependency>
        
        <!-- Dependency for admin UI components -->
        <dependency>
            <groupId>com.zheng</groupId>
            <artifactId>zheng-admin</artifactId>
            <version>1.0.0</version>
        </dependency>

        <!-- Dependency for security integration -->
        <dependency>
            <groupId>com.zheng</groupId>
            <artifactId>zheng-upms-client</artifactId>
            <version>1.0.0</version>
        </dependency>
        ...
    </dependencies>

    <build>
        <finalName>zheng-mynewmodule-admin</finalName>
        ...
        <!-- Jetty plugin for local development -->
        <plugin>
            <groupId>org.eclipse.jetty</groupId>
            <artifactId>jetty-maven-plugin</artifactId>
            <version>9.2.7.v20150116</version>
            <configuration>
                <httpConnector>
                    <port>2222</port> <!-- Ensure a unique port -->
                </httpConnector>
                ...
            </configuration>
        </plugin>
    </build>
</project>

Sources: zheng-cms/zheng-cms-admin/pom.xml

Example: zheng-mynewmodule-dao/pom.xml

The DAO module typically depends on the common sub-module and includes the mybatis-generator-maven-plugin to scaffold mappers and models from the database schema.

<project ...>
    <parent>
        <groupId>com.zheng</groupId>
        <artifactId>zheng-mynewmodule</artifactId>
        <version>1.0.0</version>
    </parent>

    <artifactId>zheng-mynewmodule-dao</artifactId>
    <packaging>jar</packaging>

    <dependencies>
        <dependency>
            <groupId>com.zheng</groupId>
            <artifactId>zheng-mynewmodule-common</artifactId>
            <version>1.0.0</version>
        </dependency>
    </dependencies>

    <build>
        ...
        <plugins>
            <plugin>
                <groupId>org.mybatis.generator</groupId>
                <artifactId>mybatis-generator-maven-plugin</artifactId>
                <version>1.3.2</version>
                ...
            </plugin>
        </plugins>
    </build>
</project>

Sources: zheng-upms/zheng-upms-dao/pom.xml

Step 3: Implement Service and Controller

With the module structure in place, you can begin implementing the business logic.

RPC API Interface

Define the service contract in the rpc-api sub-module. This interface will be used by both the service implementation and any client modules.

// zheng-demo/zheng-demo-rpc-api/src/main/java/com/zheng/demo/rpc/api/DemoService.java
package com.zheng.demo.rpc.api;

/**
 * DemoService接口
 * Created by shuzheng on 2017/01/12.
 */
public interface DemoService {

    String sayHello(String name);

}

Sources: zheng-demo/zheng-demo-rpc-api/src/main/java/com/zheng/demo/rpc/api/DemoService.java

RPC Service Implementation

Implement the DemoService interface in the rpc-service sub-module. This module will contain the core business logic.

Web Controller

In the web or admin sub-module, create controllers that consume the RPC service. The controller will inject the service interface (e.g., DemoService) and expose endpoints. The dependency graph ensures that a web module only depends on the rpc-api, not the rpc-service implementation, enforcing loose coupling.

Summary

Creating a new module in the zheng project is a standardized process that leverages its multi-module Maven architecture. The key steps are to define a new top-level module in the root pom.xml, create a parent POM for this new module, and then structure it into conventional sub-modules (common, dao, rpc-api, rpc-service, web/admin). This modular approach ensures that new features are well-organized, decoupled, and consistent with the overall project design. The zheng-demo module serves as an excellent reference implementation for bootstrapping a new module.
Sources: pom.xml, zheng-demo/pom.xml, zheng-cms/pom.xml