How to Extend the Backend with New Modules in the Mall Project

Extending the Mall backend requires creating a new Maven submodule, registering it in the root pom.xml, and implementing a Spring Boot application class that enables component scanning for your controllers and services.

The mall repository is a multi-module Maven project where each functional area (admin API, portal, search) lives in its own submodule. This guide walks you through the exact process of adding new backend capabilities without modifying existing code, leveraging the inheritance structure defined in the root pom.xml.

Understanding the Multi-Module Architecture

The project follows a standard Maven aggregator pattern. The root pom.xml declares the parent Spring Boot starter, centralizes version numbers in <dependencyManagement>, and lists all submodules in its <modules> section. According to the source code in [/pom.xml](https://github.com/macrozheng/mall/blob/master/pom.xml), versions for Spring Boot, MyBatis, JWT, and Lombok are defined once in the <properties> block (lines 30-44). Child modules inherit these versions automatically.

Existing modules demonstrate the pattern clearly. The mall-admin module provides the admin API and contains a Spring Boot starter class at [MallAdminApplication.java](https://github.com/macrozheng/mall/blob/master/mall-admin/src/main/java/com/macro/mall/MallAdminApplication.java). It depends on mall-common for reusable utilities like RequestUtil and global exception handling, as specified in [mall-common/pom.xml](https://github.com/macrozheng/mall/blob/master/mall-common/pom.xml). Because every module inherits from the parent, you can add reporting, analytics, or payment features as isolated build units while maintaining consistent dependency versions.

Step-by-Step: Adding a New Backend Module

Create the Maven Submodule

First, add a new directory with its own pom.xml at the repository root. Name it following the convention mall-<your-module> (e.g., mall-report). This directory houses your isolated build unit.

The module's pom.xml must declare the parent and include necessary dependencies:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>com.macro.mall</groupId>
        <artifactId>mall</artifactId>
        <version>1.0-SNAPSHOT</version>
        <relativePath>..</relativePath>
    </parent>

    <artifactId>mall-report</artifactId>
    <description>Reporting module for Mall backend</description>

    <dependencies>
        <dependency>
            <groupId>com.macro.mall</groupId>
            <artifactId>mall-common</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.mybatis.spring.boot</groupId>
            <artifactId>mybatis-spring-boot-starter</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

Notice that no version numbers are specified for the dependencies. Maven resolves these from the parent's <dependencyManagement> section.

Register in the Root Aggregator

Insert the new module name into the <modules> section of the root pom.xml. This ensures Maven compiles, packages, and installs your new code alongside existing modules.

<modules>
    <module>mall-admin</module>
    <module>mall-portal</module>
    <module>mall-search</module>
    <module>mall-report</module>  <!-- Your new module -->
</modules>

Implement the Spring Boot Entry Point

Create a main class annotated with @SpringBootApplication in the package com.macro.mall.<module>. This triggers Spring's component scan to automatically pick up @RestController, @Service, and @Repository beans in sub-packages.

package com.macro.mall.report;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class ReportApplication {
    public static void main(String[] args) {
        SpringApplication.run(ReportApplication.class, args);
    }
}

Place this file at mall-report/src/main/java/com/macro/mall/report/ReportApplication.java. The package root com.macro.mall matches the parent module's base package, ensuring seamless component scanning without extra @ComponentScan configuration.

Dependency Management and Shared Libraries

When you extend the backend with new modules, leverage existing shared components rather than duplicating code:

• mall-common: Provides CommonResult for API responses, RequestUtil, and global Swagger configuration. Include it as a dependency to maintain consistent response formats across all endpoints.
• mall-security: Supplies JWT-based authentication via [SecurityConfig.java](https://github.com/macrozheng/mall/blob/master/mall-security/src/main/java/com/macro/mall/security/config/SecurityConfig.java). Add this dependency if your new module requires protected endpoints.
• mall-mbg: Contains MyBatis-generated model classes and mapper interfaces. If your new module needs database access, depend on mall-mbg to reuse existing POJOs and avoid regenerating schema mappings.

Because versions are inherited from the root pom.xml, adding these dependencies requires only the group and artifact IDs, ensuring consistency with the Spring Boot and MyBatis versions used throughout the system.

Component Scanning and Package Structure

Spring Boot automatically scans all sub-packages of the class annotated with @SpringBootApplication. In the mall project, placing your main class under com.macro.mall (or a sub-package like com.macro.mall.report) ensures that any class annotated with @RestController, @Service, or @Mapper is discovered without explicit configuration.

For example, controllers in mall-admin follow this pattern naturally. The UmsAdminController in [mall-admin/src/main/java/com/macro/mall/controller/UmsAdminController.java](https://github.com/macrozheng/mall/blob/master/mall-admin/src/main/java/com/macro/mall/controller/UmsAdminController.java) resides under com.macro.mall.controller, which is a sub-package of the main class location com.macro.mall. Your new module should follow the same structure: place controllers under com.macro.mall.<module>.controller, services under .service, and mappers under .mapper.

Complete Working Example: The Reporting Module

Below is a minimal implementation of a mall-report module that exposes a health-check endpoint.

Controller Implementation:

package com.macro.mall.report.controller;

import com.macro.mall.common.api.CommonResult;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ReportController {

    @GetMapping("/report/health")
    public CommonResult<String> health() {
        return CommonResult.success("Report service is up");
    }
}

Place this file at mall-report/src/main/java/com/macro/mall/report/controller/ReportController.java. The CommonResult class automatically provides standardized JSON responses because the module depends on mall-common.

Build and Execution:

mvn clean install
java -jar mall-report/target/mall-report-1.0-SNAPSHOT.jar

The service starts independently on the default port (8080) unless overridden in application.yml. You can verify functionality by calling GET /report/health.

Summary

• Create a Maven submodule with its own pom.xml inheriting from the root parent to isolate your new feature while maintaining version consistency.
• Register the module in the root pom.xml <modules> section so Maven includes it in the build lifecycle.
• Implement a Spring Boot entry class annotated with @SpringBootApplication in the com.macro.mall package tree to enable automatic component scanning.
• Reuse shared libraries by depending on mall-common for utilities, mall-security for JWT authentication, and mall-mbg for database models.
• Follow package conventions (com.macro.mall.<module>.*) to ensure Spring discovers your controllers and services without explicit configuration.

Frequently Asked Questions

Do I need to specify version numbers for Spring Boot or MyBatis in the new module?

No. The root pom.xml defines all versions in its <dependencyManagement> section (lines 30-44). Your new module inherits these, so you only declare the artifact coordinates (groupId and artifactId) without version tags. This guarantees your new code uses the same Spring Boot and MyBatis versions as the existing mall-admin and mall-portal modules.

How can the new module access existing database tables and models?

Add a dependency on mall-mbg in your module's pom.xml. This module contains the MyBatis-generated POJOs and mapper interfaces for the entire schema. By depending on mall-mbg, you reuse existing model classes and XML mappers rather than duplicating them, maintaining consistency with the database layer used by mall-admin.

Can I run the new module independently from other services?

Yes. Each module is a standalone Spring Boot application. After building with mvn clean install, you can start only your new module using java -jar mall-report/target/mall-report-1.0-SNAPSHOT.jar without starting mall-admin or other services. This supports microservice-style deployment where different backend capabilities run as separate processes.

Where should I configure security and JWT authentication for the new module?

Include the mall-security dependency in your module's pom.xml and reuse the security configuration provided in [mall-security/src/main/java/com/macro/mall/security/config/SecurityConfig.java](https://github.com/macrozheng/mall/blob/master/mall-security/src/main/java/com/macro/mall/security/config/SecurityConfig.java). This class configures JWT-based authentication. By importing this module, your new endpoints integrate with the existing authentication flow used by the admin and portal APIs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}