Quick Start

Option 1: Generate with the Archetype (Recommended)

Best for new services. Run the command in the parent directory where you want the project placed (e.g. ~/projects); the generator creates a new folder named after the artifactId in the current directory:

mvn archetype:generate \
    -DarchetypeGroupId=io.github.weihubeats \
    -DarchetypeArtifactId=spring-boot-nebula-archetype \
    -DarchetypeVersion=3.0.6 \
    -DgroupId=com.example \
    -DartifactId=demo \
    -Dversion=1.0.0-SNAPSHOT \
    -Dpackage=com.example.demo \
    -DinteractiveMode=false

Once generated, the project runs out of the box:

cd demo && mvn verify && mvn spring-boot:run -pl demo-start

See Project Archetype for details.

Option 2: Manual Integration

1. Import the BOM (Recommended)

Manage versions centrally in the parent POM to avoid inconsistent dependency versions across projects (e.g. behavioral differences between Redisson 3.14 and 3.61):

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.github.weihubeats</groupId>
            <artifactId>spring-boot-nebula-dependencies</artifactId>
            <version>3.0.6</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

2. Add the Web Module

<dependency>
    <groupId>io.github.weihubeats</groupId>
    <artifactId>spring-boot-nebula-web</artifactId>
</dependency>

3. Write the Application Class

@SpringBootApplication
public class WebApplication {

    public static void main(String[] args) {
        TimeZone.setDefault(TimeZone.getTimeZone("Asia/Shanghai"));
        SpringApplication.run(WebApplication.class, args);
    }
}

4. Write an Endpoint

No manual Response wrapping needed — just annotate the controller method with @NebulaResponseBody (it can also be placed on the class to apply to all methods):

@GetMapping("/test")
@NebulaResponseBody
public String test() {
    return "小奏";
}

Response format:

{
  "code": 200,
  "data": "小奏",
  "msg": "success"
}

5. Add More Modules as Needed

Capability	ArtifactId	Docs
MyBatis-Plus wrapper	spring-boot-nebula-mybatis	View
Read/write splitting	spring-boot-nebula-dynamic-datasource	View
Distributed lock	spring-boot-nebula-distribute-lock	View
Excel import/export	spring-boot-nebula-excel	View
Region-routing JOIN	spring-boot-nebula-join	View
Feign unwrapping	spring-boot-nebula-feign	View
Log masking & alerting	spring-boot-nebula-logback	View
DDD aggregate root	spring-boot-nebula-aggregate	View

Run Samples Locally

Every capability ships with a runnable minimal sample under spring-boot-nebula-samples:

cd spring-boot-nebula-samples/spring-boot-nebula-web-sample
mvn spring-boot:run