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

> Easily extend the Mall backend with new modules. Learn to create Maven submodules, register them in pom.xml, and implement Spring Boot applications for new features.

- Repository: [macro/mall](https://github.com/macrozheng/mall)
- Tags: how-to-guide
- Published: 2026-02-28

---

**Extending the Mall backend requires creating a new Maven submodule, registering it in the root [`pom.xml`](https://github.com/macrozheng/mall/blob/main/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`](https://github.com/macrozheng/mall/blob/main/pom.xml).

## Understanding the Multi-Module Architecture

The project follows a standard Maven aggregator pattern. The **root [`pom.xml`](https://github.com/macrozheng/mall/blob/main/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/main//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/main/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/main/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`](https://github.com/macrozheng/mall/blob/main/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`](https://github.com/macrozheng/mall/blob/main/pom.xml) must declare the parent and include necessary dependencies:

```xml
<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`](https://github.com/macrozheng/mall/blob/main/pom.xml). This ensures Maven compiles, packages, and installs your new code alongside existing modules.

```xml
<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.

```java
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`](https://github.com/macrozheng/mall/blob/main/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/main/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`](https://github.com/macrozheng/mall/blob/main/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/main/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:**

```java
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`](https://github.com/macrozheng/mall/blob/main/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:**

```bash
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`](https://github.com/macrozheng/mall/blob/main/application.yml). You can verify functionality by calling `GET /report/health`.

## Summary

- **Create a Maven submodule** with its own [`pom.xml`](https://github.com/macrozheng/mall/blob/main/pom.xml) inheriting from the root parent to isolate your new feature while maintaining version consistency.
- **Register the module** in the root [`pom.xml`](https://github.com/macrozheng/mall/blob/main/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`](https://github.com/macrozheng/mall/blob/main/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`](https://github.com/macrozheng/mall/blob/main/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`](https://github.com/macrozheng/mall/blob/main/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/main/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.