docs: quick start

.dumirc.ts

@@ -4,7 +4,7 @@ export default defineConfig({
   themeConfig: {
     name: 'mapstruct-plus',
     logo: false,
-    nav: [{ title: '指南', link: '/guide' }],
+    autoAlias: false,
     prefersColor: { default: 'auto' },
     github: 'https://github.com/linpeilie',
     footer: false

docs/guide.md

@@ -1 +0,0 @@
-This is a guide example.

docs/guide/index.md

@@ -0,0 +1,7 @@
+---
+nav: 指南
+---
+
+# 介绍
+
+这里是 MapStruct Plus 的介绍

docs/guide/quick-start.md

@@ -0,0 +1,203 @@
+# 快速开始
+
+下面演示如何使用 MapStruct Plus 来映射两个对象。
+
+假设有两个类 `UserDto` 和 `User`，分别表示数据层对象和业务层对象：
+
+- `UserDto`
+
+```java
+public class UserDto {
+    private String username;
+    private int age;
+    private boolean young;
+
+    // getter、setter、toString、equals、hashCode
+}
+```
+
+- `User`
+
+```java
+public class User {
+    private String username;
+    private int age;
+    private boolean young;
+
+    // getter、setter、toString、equals、hashCode
+}
+```
+
+## 非 Spring 环境
+
+### 添加依赖
+
+引入 `mapstruct-plus` 依赖：
+
+```xml
+<properties>
+    <mapstruct-plus.version>最新版本</mapstruct-plus.version>
+</properties>
+<dependencies>
+    <dependency>
+        <groupId>io.github.linpeilie</groupId>
+        <artifactId>mapstruct-plus</artifactId>
+        <version>{mapstruct-plus.version}</version>
+    </dependency>
+</dependencies>
+<build>
+    <plugins>
+        <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-compiler-plugin</artifactId>
+            <version>3.8.1</version>
+            <configuration>
+                <source>1.8</source>
+                <target>1.8</target>
+                <annotationProcessorPaths>
+                    <path>
+                        <groupId>io.github.linpeilie</groupId>
+                        <artifactId>mapstruct-plus-processor</artifactId>
+                        <version>${mapstruct-plus.version}</version>
+                    </path>
+                </annotationProcessorPaths>
+            </configuration>
+        </plugin>
+    </plugins>
+</build>
+```
+
+### 添加配置类
+
+在 Bean 对象所在模块包中，任意类上增加注解：`@ComponentModelConfig(componentModel = "default")`
+
+例如：
+
+```java
+@ComponentModelConfig(componentModel = "default")
+public class MapperConfiguration {
+}
+```
+
+### 指定对象映射关系
+
+在 `User` 或者 `UserDto` 上面增加注解 —— `@AutoMapper`，并设置 `targetType` 为对方类。
+
+例如：
+
+```java
+@AutoMapper(target = UserDto.class)
+public class User {
+    // ...
+}
+```
+
+### 测试
+
+```java
+public class QuickStart {
+
+    private static Converter converter = new Converter();
+
+    public static void main(String[] args) {
+        User user = new User();
+        user.setUsername("jack");
+        user.setAge(23);
+        user.setYoung(false);
+
+        UserDto userDto = converter.convert(user, UserDto.class);
+        System.out.println(userDto);    // UserDto{username='jack', age=23, young=false}
+
+        assert user.getUsername().equals(userDto.getUsername());
+        assert user.getAge() == userDto.getAge();
+        assert user.isYoung() == userDto.isYoung();
+
+        User newUser = converter.convert(userDto, User.class);
+
+        System.out.println(newUser);    // User{username='jack', age=23, young=false}
+
+        assert user.getUsername().equals(newUser.getUsername());
+        assert user.getAge() == newUser.getAge();
+        assert user.isYoung() == newUser.isYoung();
+    }
+
+}
+```
+
+## SpringBoot 环境
+
+### 添加依赖
+
+引入 `mapstruct-plus-spring-boot-starter` 依赖：
+
+```xml
+<properties>
+    <mapstruct-plus.version>最新版本</mapstruct-plus.version>
+</properties>
+<dependencies>
+    <dependency>
+        <groupId>io.github.linpeilie</groupId>
+        <artifactId>mapstruct-plus</artifactId>
+        <version>{mapstruct-plus.version}</version>
+    </dependency>
+</dependencies>
+<build>
+    <plugins>
+        <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-compiler-plugin</artifactId>
+            <version>3.8.1</version>
+            <configuration>
+                <source>1.8</source>
+                <target>1.8</target>
+                <annotationProcessorPaths>
+                    <path>
+                        <groupId>io.github.linpeilie</groupId>
+                        <artifactId>mapstruct-plus-processor</artifactId>
+                        <version>${mapstruct-plus.version}</version>
+                    </path>
+                </annotationProcessorPaths>
+            </configuration>
+        </plugin>
+    </plugins>
+</build>
+```
+
+### 指定对象映射关系
+
+同非 Spring 环境
+
+### 测试
+
+```java
+@SpringBootTest
+public class QuickStartTest {
+
+    @Autowired
+    private Converter converter;
+
+    @Test
+    public void test() {
+        User user = new User();
+        user.setUsername("jack");
+        user.setAge(23);
+        user.setYoung(false);
+
+        UserDto userDto = converter.convert(user, UserDto.class);
+        System.out.println(userDto);    // UserDto{username='jack', age=23, young=false}
+
+        assert user.getUsername().equals(userDto.getUsername());
+        assert user.getAge() == userDto.getAge();
+        assert user.isYoung() == userDto.isYoung();
+
+        User newUser = converter.convert(userDto, User.class);
+
+        System.out.println(newUser);    // User{username='jack', age=23, young=false}
+
+        assert user.getUsername().equals(newUser.getUsername());
+        assert user.getAge() == newUser.getAge();
+        assert user.isYoung() == newUser.isYoung();
+    }
+
+}
+```

example/pom.xml

@@ -59,11 +59,6 @@
                     <source>1.8</source>
                     <target>1.8</target>
                     <annotationProcessorPaths>
-                        <path>
-                            <groupId>org.mapstruct</groupId>
-                            <artifactId>mapstruct-processor</artifactId>
-                            <version>${mapstruct.version}</version>
-                        </path>
                         <path>
                             <groupId>io.github.linpeilie</groupId>
                             <artifactId>mapstruct-plus-processor</artifactId>

example/quick-start/src/main/java/io/github/linpeilie/QuickStart.java

@@ -1,20 +1,32 @@
 package io.github.linpeilie;
 
-import io.github.linpeilie.model.Car;
+import io.github.linpeilie.model.User;
-import io.github.linpeilie.model.CarDto;
+import io.github.linpeilie.model.UserDto;
-import io.github.linpeilie.model.CarType;
 
 public class QuickStart {
 
     private static Converter converter = new Converter();
 
     public static void main(String[] args) {
+        User user = new User();
+        user.setUsername("jack");
+        user.setAge(23);
+        user.setYoung(false);
 
-        final Car car = new Car();
+        UserDto userDto = converter.convert(user, UserDto.class);
-        car.setType(CarType.OTHER);
+        System.out.println(userDto);    // UserDto{username='jack', age=23, young=false}
 
-        final CarDto carDto = converter.convert(car, CarDto.class);
+        assert user.getUsername().equals(userDto.getUsername());
-        System.out.println(carDto);
+        assert user.getAge() == userDto.getAge();
+        assert user.isYoung() == userDto.isYoung();
+
+        User newUser = converter.convert(userDto, User.class);
+
+        System.out.println(newUser);    // User{username='jack', age=23, young=false}
+
+        assert user.getUsername().equals(newUser.getUsername());
+        assert user.getAge() == newUser.getAge();
+        assert user.isYoung() == newUser.isYoung();
     }
 
 }

example/quick-start/src/main/java/io/github/linpeilie/model/User.java

@@ -0,0 +1,63 @@
+package io.github.linpeilie.model;
+
+import io.github.linpeilie.annotations.AutoMapper;
+import java.util.Objects;
+
+@AutoMapper(target = UserDto.class)
+public class User {
+
+    private String username;
+    private int age;
+    private boolean young;
+
+    public String getUsername() {
+        return username;
+    }
+
+    public void setUsername(final String username) {
+        this.username = username;
+    }
+
+    public int getAge() {
+        return age;
+    }
+
+    public void setAge(final int age) {
+        this.age = age;
+    }
+
+    public boolean isYoung() {
+        return young;
+    }
+
+    public void setYoung(final boolean young) {
+        this.young = young;
+    }
+
+    @Override
+    public boolean equals(final Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+        final User user = (User) o;
+        return getAge() == user.getAge() && isYoung() == user.isYoung() &&
+               Objects.equals(getUsername(), user.getUsername());
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(getUsername(), getAge(), isYoung());
+    }
+
+    @Override
+    public String toString() {
+        return "User{" +
+               "username='" + username + '\'' +
+               ", age=" + age +
+               ", young=" + young +
+               '}';
+    }
+}

example/quick-start/src/main/java/io/github/linpeilie/model/UserDto.java

@@ -0,0 +1,62 @@
+package io.github.linpeilie.model;
+
+import java.util.Objects;
+
+public class UserDto {
+
+    private String username;
+    private int age;
+    private boolean young;
+
+    public String getUsername() {
+        return username;
+    }
+
+    public void setUsername(final String username) {
+        this.username = username;
+    }
+
+    public int getAge() {
+        return age;
+    }
+
+    public void setAge(final int age) {
+        this.age = age;
+    }
+
+    public boolean isYoung() {
+        return young;
+    }
+
+    public void setYoung(final boolean young) {
+        this.young = young;
+    }
+
+    @Override
+    public boolean equals(final Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+        final UserDto user = (UserDto) o;
+        return getAge() == user.getAge() && isYoung() == user.isYoung() &&
+               Objects.equals(getUsername(), user.getUsername());
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(getUsername(), getAge(), isYoung());
+    }
+
+    @Override
+    public String toString() {
+        return "UserDto{" +
+               "username='" + username + '\'' +
+               ", age=" + age +
+               ", young=" + young +
+               '}';
+    }
+
+}

example/spring-boot/pom.xml

@@ -22,6 +22,10 @@
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-web</artifactId>
         </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-test</artifactId>
+        </dependency>
         <dependency>
             <groupId>io.github.linpeilie</groupId>
             <artifactId>mapstruct-plus-spring-boot-starter</artifactId>

example/spring-boot/src/main/java/io/github/linpeilie/model/User.java

@@ -0,0 +1,63 @@
+package io.github.linpeilie.model;
+
+import io.github.linpeilie.annotations.AutoMapper;
+import java.util.Objects;
+
+@AutoMapper(target = UserDto.class)
+public class User {
+
+    private String username;
+    private int age;
+    private boolean young;
+
+    public String getUsername() {
+        return username;
+    }
+
+    public void setUsername(final String username) {
+        this.username = username;
+    }
+
+    public int getAge() {
+        return age;
+    }
+
+    public void setAge(final int age) {
+        this.age = age;
+    }
+
+    public boolean isYoung() {
+        return young;
+    }
+
+    public void setYoung(final boolean young) {
+        this.young = young;
+    }
+
+    @Override
+    public boolean equals(final Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+        final User user = (User) o;
+        return getAge() == user.getAge() && isYoung() == user.isYoung() &&
+               Objects.equals(getUsername(), user.getUsername());
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(getUsername(), getAge(), isYoung());
+    }
+
+    @Override
+    public String toString() {
+        return "User{" +
+               "username='" + username + '\'' +
+               ", age=" + age +
+               ", young=" + young +
+               '}';
+    }
+}

example/spring-boot/src/main/java/io/github/linpeilie/model/UserDto.java

@@ -0,0 +1,62 @@
+package io.github.linpeilie.model;
+
+import java.util.Objects;
+
+public class UserDto {
+
+    private String username;
+    private int age;
+    private boolean young;
+
+    public String getUsername() {
+        return username;
+    }
+
+    public void setUsername(final String username) {
+        this.username = username;
+    }
+
+    public int getAge() {
+        return age;
+    }
+
+    public void setAge(final int age) {
+        this.age = age;
+    }
+
+    public boolean isYoung() {
+        return young;
+    }
+
+    public void setYoung(final boolean young) {
+        this.young = young;
+    }
+
+    @Override
+    public boolean equals(final Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+        final UserDto user = (UserDto) o;
+        return getAge() == user.getAge() && isYoung() == user.isYoung() &&
+               Objects.equals(getUsername(), user.getUsername());
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(getUsername(), getAge(), isYoung());
+    }
+
+    @Override
+    public String toString() {
+        return "UserDto{" +
+               "username='" + username + '\'' +
+               ", age=" + age +
+               ", young=" + young +
+               '}';
+    }
+
+}

example/spring-boot/src/test/java/io/github/linpeilie/QuickStartTest.java

@@ -0,0 +1,38 @@
+package io.github.linpeilie;
+
+import io.github.linpeilie.model.User;
+import io.github.linpeilie.model.UserDto;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+
+@SpringBootTest
+public class QuickStartTest {
+
+    @Autowired
+    private Converter converter;
+
+    @Test
+    public void test() {
+        User user = new User();
+        user.setUsername("jack");
+        user.setAge(23);
+        user.setYoung(false);
+
+        UserDto userDto = converter.convert(user, UserDto.class);
+        System.out.println(userDto);    // UserDto{username='jack', age=23, young=false}
+
+        assert user.getUsername().equals(userDto.getUsername());
+        assert user.getAge() == userDto.getAge();
+        assert user.isYoung() == userDto.isYoung();
+
+        User newUser = converter.convert(userDto, User.class);
+
+        System.out.println(newUser);    // User{username='jack', age=23, young=false}
+
+        assert user.getUsername().equals(newUser.getUsername());
+        assert user.getAge() == newUser.getAge();
+        assert user.isYoung() == newUser.isYoung();
+    }
+
+}

mapstruct-plus-processor/pom.xml

@@ -31,6 +31,10 @@
             <groupId>org.apache.commons</groupId>
             <artifactId>commons-lang3</artifactId>
         </dependency>
+        <dependency>
+            <groupId>org.mapstruct</groupId>
+            <artifactId>mapstruct-processor</artifactId>
+        </dependency>
     </dependencies>
 
     <build>

mapstruct-plus-processor/src/main/resources/META-INF/services/javax.annotation.processing.Processor

@@ -1 +1,2 @@
 io.github.linpeilie.processor.AutoMapperProcessor
+org.mapstruct.ap.MappingProcessor

mapstruct-plus/src/main/java/io/github/linpeilie/DefaultConverterFactory.java

@@ -7,6 +7,7 @@ import java.net.URL;
 import java.util.ArrayList;
 import java.util.Enumeration;
 import java.util.List;
+import java.util.regex.Matcher;
 import org.mapstruct.factory.Mappers;
 
 public class DefaultConverterFactory extends AbstractCachedConverterFactory {
@@ -61,7 +62,8 @@ public class DefaultConverterFactory extends AbstractCachedConverterFactory {
             }
             try {
                 String classPath = file.getPath();
-                String className = classPath.substring(root.length() + 1, classPath.length() - 6).replaceAll("/", ".");
+                String className = classPath.substring(root.length() + 1, classPath.length() - 6)
+                    .replaceAll(Matcher.quoteReplacement(File.separator), ".");
                 classes.add(classLoader.loadClass(className));
             } catch (Exception e) {
                 e.printStackTrace();

mapstruct-plus/src/main/java/io/github/linpeilie/annotations/ComponentModelConfig.java

@@ -9,6 +9,6 @@ import java.lang.annotation.Target;
 @Retention(RetentionPolicy.SOURCE)
 public @interface ComponentModelConfig {
 
-    String componentModel() default "default";
+    String componentModel() default "spring";
 
 }

pom.xml

@@ -19,6 +19,7 @@
         <maven.compiler.source>8</maven.compiler.source>
         <maven.compiler.target>8</maven.compiler.target>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <mapstruct.version>1.5.1.Final</mapstruct.version>
     </properties>
 
     <dependencyManagement>
@@ -46,7 +47,12 @@
             <dependency>
                 <groupId>org.mapstruct</groupId>
                 <artifactId>mapstruct</artifactId>
-                <version>1.5.1.Final</version>
+                <version>${mapstruct.version}</version>
+            </dependency>
+            <dependency>
+                <groupId>org.mapstruct</groupId>
+                <artifactId>mapstruct-processor</artifactId>
+                <version>${mapstruct.version}</version>
             </dependency>
             <dependency>
                 <groupId>org.springframework</groupId>