feat: 调整 archetype

shoulder-generator/README.md

@@ -1,3 +1,8 @@
 # [shoulder-generator](https://github.com/ChinaLym/Shoulder-Platform/tree/main/shoulder-generator)
 
 代码生成器，根据数据库表，自动生成 controller、service、entity，带有基本的增删改查、前端界面的web工程
+
+
+---
+
+只使用发布于 maven 中央仓库中的依赖，使得本应用调试简单，无需额外成本。

shoulder-generator/pom.xml

@@ -12,6 +12,7 @@
     <artifactId>shoulder-generator</artifactId>
     <name>代码生成器</name>
     <description>代码生成器</description>
+
     <dependencies>
 
         <dependency>

shoulder-generator/src/main/java/cn/itlym/shoulder/generator/model/TableEntity.java

@@ -30,6 +30,11 @@ public class TableEntity {
      */
     private boolean checkAuth;
 
+    /**
+     * Controller 中生成异步批量操作接口。
+     */
+    private boolean asyncBatch;
+
     /**
      * 表类型：
      * TREE(parent_id), CREATOR, MODIFIER, CREATOR_TIME, UPDATE_TIME, BATCH

shoulder-generator/src/main/resources/template/Api.java.vm

@@ -0,0 +1,181 @@
+package ${package}.${pkgName}.controller;
+
+import java.util.Map;
+
+import io.swagger.annotations.Api;
+import org.apache.commons.collections4.CollectionUtils;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.web.bind.annotation.*;
+#if(${checkAuth})
+import org.springframework.security.access.prepost.PreAuthorize;
+#end
+import org.shoulder.core.dto.response.PageResult;
+import org.shoulder.core.dto.response.RestResult;
+
+import ${package}.${pkgName}.convert.${className}Converter;
+import ${package}.${pkgName}.dto.${className}DTO;
+import ${package}.${pkgName}.model.${className};
+import ${package}.${pkgName}.service.${className}Service;
+
+/**
+ * ${comments} 控制器
+ *
+ * @author ${author}
+ * @date ${datetime}
+ */
+@RestController
+@RequestMapping("${pathName}")
+@Api(tags = "${comments}")
+public interface ${className}Controller {
+
+    /**
+     * 条件查询，分页
+     * @param condition 查询条件
+     * @return 分页结果
+     */
+    @RequestMapping("list")
+#if(${checkAuth})
+    @PreAuthorize("hasAnyAuthority('${tableName}:${pathName}:list')")
+#end
+    public PageResult list(@RequestParam Map<String, Object> condition);
+
+
+    /**
+     * 保存单个，推荐使用幂等的 PUT 方法，体现接口幂等性。为了方便习惯，也开放了 POST
+     *
+     * @param ${lowClassName}DTO 新增数据
+     * @return 保存成功
+     */
+    @RequestMapping(value = "save", method = {RequestMethod.PUT, RequestMethod.POST})
+#if(${checkAuth})
+    @PreAuthorize("hasAnyAuthority('resource:sysroleuser:save')")
+#end
+    public RestResult save(@RequestBody ${className}DTO ${lowClassName}DTO);
+
+    /**
+     * 单个修改
+     *
+     * @param ${lowClassName}DTO 修改属性
+     * @return 修改成功
+     */
+    @PostMapping("update")
+#if(${checkAuth})
+    @PreAuthorize("hasAnyAuthority('resource:sysroleuser:update')")
+#end
+    public RestResult update(@RequestBody ${className}DTO ${lowClassName}DTO);
+
+    /**
+     * 根据 id 删除单个
+     *
+     * @param ${pk.attributeName} id
+     * @return 删除成功
+     */
+    @RequestMapping(value = "delete/{id}", method = {RequestMethod.DELETE, RequestMethod.POST})
+#if(${checkAuth})
+    @PreAuthorize("hasAnyAuthority('resource:sysroleuser:delete')")
+#end
+    public RestResult delete(@PathVariable Long ${pk.attributeName});
+
+    /**
+     * 根据 id 批量删除
+     *
+     * @param idList ids
+     * @return 删除成功
+     */
+    @RequestMapping(value = "delete", method = {RequestMethod.DELETE, RequestMethod.POST})
+#if(${checkAuth})
+    @PreAuthorize("hasAnyAuthority('resource:sysroleuser:delete')")
+#end
+    public RestResult delete(List<Long> idList);
+
+
+#if(${asyncBatch})
+    // ======================== 异步批量操作 ============================
+
+    /**
+     * 批量新增 ${comments} - 校验
+     *
+     * @param addDtoList 要批量添加的数据
+     * @return 校验任务标识
+     **/
+    @ApiOperation(value = "批量新增 ${comments} - 校验", notes = "批量新增 ${comments} - 校验")
+    @PostMapping("validateAdd")
+    @ApiImplicitParams({
+            @ApiImplicitParam(paramType = "body", required = true, name = "addDtoList", dataType = "list",
+                    value = "${comments}列表", example = "[{\"id\":\"12345\",\"name\":\"foo\"}]"),
+    })
+    RestResult<String> validateAdd(@RequestBody List<${className}DTO> addDtoList);
+
+    /**
+     * 批量修改 ${comments} - 校验
+     *
+     * @param updatedDtoList 要批量修改的数据
+     * @return 校验任务标识
+     **/
+    @ApiOperation(value = "批量修改 ${comments} - 校验", notes = "批量修改 ${comments} - 校验")
+    @PostMapping("validateUpdate")
+    @ApiImplicitParams({
+            @ApiImplicitParam(paramType = "body", required = true, name = "updatedDtoList", dataType = "list",
+                    value = "${comments}列表", example = "[{\"id\":\"12345\",\"name\":\"foo\"}]"),
+
+    })
+    RestResult<String> validateUpdate(@RequestBody List<${className}DTO> updatedDtoList);
+
+
+    /**
+     * 查询批量校验进度 todo 框架提供
+     *
+     * @param progressParam 异步任务标识
+     * @return 校验进度
+     **/
+    @ApiOperation(value = "查询批量校验进度", notes = "根据批量校验接口返回的异步任务标识查询校验进度")
+    @PostMapping("validateProgress")
+    @ApiImplicitParam(paramType = "query", required = true, name = "clientId", dataType = "String",
+            value = "批量校验标识", example = "50c77859-a670-47a8-a666-fff12816d832")
+    RestResult<ImportProcessDTO> batchValidateProgress(@RequestBody ProgressParam progressParam);
+
+    /**
+     * 批量添加
+     *
+     * 根据 taskId 从缓存中取出对应的校验通过数据执行添加
+     *
+     * @param batchAddOperationParam 批量添加操作参数
+     * @return 异步任务标识
+     **/
+    @ApiOperation(value = "批量添加 ${comments}", notes = "根据 异步任务标识 从缓存中取出对应的校验通过数据执行批量添加")
+    @PostMapping("addBatch")
+    RestResult<Object> addBatch(@RequestBody BatchAddOperationParam batchAddOperationParam) throws Exception;
+
+    /**
+     * 批量更新
+     *
+     * 根据 taskId 从缓存中取出对应的校验通过数据执行更新
+     *
+     * @param batchAddOperationParam 批量更新操作参数
+     * @return 异步任务标识
+     **/
+    @ApiOperation(value = "批量更新 ${comments}", notes = "根据 异步任务标识 从缓存中取出对应的校验通过数据执行批量更新")
+    @PostMapping("updateBatch")
+    @ApiImplicitParam(paramType = "body", required = true, name = "deviceBatchManageDto", dataType =
+            "DeviceBatchManageDto", value = "批量修改DTO",
+            example = "{\"taskId\":\"716acbae-f407-43ed-bbac-c36dd7df7094\"}")
+    RestResult<Object> updateBatch(@RequestBody BatchAddOperationParam batchAddOperationParam) throws Exception;
+
+
+    /**
+     * 查询批量操作进度 todo 框架提供
+     *
+     * @param progressParam 异步任务标识
+     * @return 执行结果
+     **/
+    @ApiOperation(value = "查询批量操作进度", notes = "根据批量操作接口返回的异步任务标识查询操作进度")
+    @PostMapping("operationProgress")
+    @ApiImplicitParam(paramType = "query", required = true, name = "clientId", dataType = "String",
+            value = "批量操作标识", example = "649b545c-0edd-425b-b6b6-e1bc9ba6583f")
+    RestResult<ImportProcessResult> batchOperationProgress(@RequestBody ProgressParam progressParam)
+            throws Exception;
+#end
+
+
+
+}

shoulder-generator/src/main/resources/template/Controller.java.vm

@@ -18,7 +18,7 @@ import ${package}.${pkgName}.model.${className};
 import ${package}.${pkgName}.service.${className}Service;
 
 /**
- * ${comments}
+ * ${comments} 控制器
  *
  * @author ${author}
  * @date ${datetime}
@@ -112,4 +112,61 @@ public class ${className}Controller {
         return RestResult.success();
     }
 
+
+
+
+    /**
+     * 批量新增 ${comments} - 校验
+     *
+     * @param deviceList
+     * @return ControllerResultDTO<java.lang.String>
+     **/
+    @ApiOperation(value = "校验批量新增设备", notes = "校验批量新增设备")
+    @PostMapping("service/rs/v1/deviceService/validateImpDeviceData")
+    @ApiImplicitParams({
+            @ApiImplicitParam(paramType = "body", required = true, name = "deviceList", dataType = "list", value =
+                    "设备集合", example = "[{\"driver\":\"23123123\",\"name\":\"报警设备\"}]"),
+    })
+    ControllerResultDTO<String> validateImpDeviceData(@RequestBody List<Map<String, String>> deviceList);
+
+    /**
+     * 校验批量修改设备
+     *
+     * @param deviceList
+     * @return ControllerResultDTO<java.lang.String>
+     **/
+    @ApiOperation(value = "校验批量修改设备", notes = "校验批量修改设备")
+    @PostMapping("service/rs/v1/deviceService/validateUpdateDeviceData")
+    @ApiImplicitParams({
+            @ApiImplicitParam(paramType = "body", required = true, name = "deviceList", dataType = "list", value =
+                    "设备集合", example = "[{\"driver\":\"23123123\",\"name\":\"报警设备\"}]"),
+
+    })
+    ControllerResultDTO<String> validateUpdateDeviceData(@RequestBody List<Map<String, String>> deviceList);
+
+    /**
+     * 设备批量添加
+     *
+     * @param deviceBatchManageDto
+     * @return ControllerResultDTO<java.lang.Object>
+     **/
+    @ApiOperation(value = "设备批量添加", notes = "批量添加同一资源类型的设备，异步获取该批设备的设备和通道信息。")
+    @PostMapping("service/rs/v1/deviceService/addBatch")
+    ControllerResultDTO<Object> addBatch(@RequestBody DeviceBatchManageDto deviceBatchManageDto);
+
+    /**
+     * 设备批量更新
+     *
+     * @param deviceBatchManageDto
+     * @return ControllerResultDTO<java.lang.Object>
+     **/
+    @ApiOperation(value = "设备批量更新", notes = "批量更新设备信息")
+    @PostMapping("service/rs/v1/deviceService/updateBatch")
+    @ApiImplicitParams({
+            @ApiImplicitParam(paramType = "body", required = true, name = "deviceBatchManageDto", dataType =
+                    "DeviceBatchManageDto", value = "批量修改设备DTO", example = ""),
+    })
+    ControllerResultDTO<Object> updateBatch(@RequestBody DeviceBatchManageDto deviceBatchManageDto) throws Exception;
+
+
 }

shoulder-platform-common/shoulder-platform-archetype/CHANGELOG.MD

@@ -0,0 +1,11 @@
+# 更新记录
+
+## 1.0 （doing）
+
+- 设计出模块划分
+
+
+- todo 是否提供领域内部详细设计方案示例
+    - 新开一个 ddd-archetype?
+
+

shoulder-platform-common/shoulder-platform-archetype/README.md

@@ -93,6 +93,45 @@ version     1.0-SNAPSHOT
 
 ![目录结构](../../img/archetype/projectAndModule.png)
 
+
+### 关于领域层和基础设施层
+
+关于`领域层`和`基础设施层`通常有两种设计，这两种设计都不会过多的侵入类间关系的设计，区别在于实现成本、复杂度、修改外部依赖时的开放封闭。
+
+主要是缓存、持久化存储、消息通知的接口定义在哪？
+
+> 因为这些接口定义必然不会涉及到技术实现，但又一定程度上与业务绑定，如 UserRepository，确实与技术无关，可以 mysql、es、mongo等等，但又一定程度上携带了业务，如 `findAllActive`
+
+#### 领域层依赖基础设施层
+
+* 优点：成本更低、类更少，理解简单，且基础设施层可以在各个工程中复用，减少系统内的重复代码。
+
+* 缺点：领域层中会包含外部依赖，若外部依赖变更，需要一定程度上修改领域层的代码。但首先依赖通常不会变更，且即使变更，由于领域层接口定义不依赖外部，故影响的通常也只是实现类，对于接口无影响。
+
+* 适合初建型项目，充分复用基础设施层代码、减少系统的代码量、理解更简单，开发更快速，适合原型、探索阶段的项目。
+
+#### 基础设施层依赖领域层
+
+通过依赖倒置，将不变的部分在领域层中以接口方式定义，实现类放在基础设施层。
+
+* 优点：外部依赖变更可以实现不需要改动领域层代码。在基础设施层中可以访问领域层内容。
+
+* 缺点：各工程之间的基础设施层无法复用，容易造成多个子系统有大量代码冗余；增加理解难度和开发成本；类会更多，增加系统复杂性。
+    
+* 适合领域/业务已经比较明确，长时间维护的大型系统。
+
+
+### Shoulder-Platform 中的设计
+
+不是所有东西都是非A即B的，也不是用了优点就必然存在缺点的，Shoulder 结合了两种设计，通过模块拆的更细，将两者的优缺点结合在一起。既可以重复利用，减少无意义的重复，又可以隔离基础层、边界层的易变更项。
+
+如 `Cache`、`Repository`、`MessageNotify` 接口定义在`领域层`还是`基础设施层`？
+
+通过上面的比较，发现无论定义在哪一次，都有利弊，为了充分汲取两者的优势，将这部分抽象定义在单独的模块，保证了切换底层实现，接口定义不变，从而保证领域层的稳定性，即实现了`领域层不依赖特定的技术实现`，同时一个大的系统内部可以共同复用这部分定义，也简化了使用新技术的替换成本（直接继承这个模块，以插件形式开发，而无需继承整个领域层），且开发出来的新的实现项又是可以复用的。
+
+
+> 无论是 Shoulder-Framework 中还是 Platform 中，你会经常看到通过一些巧妙手法的将两种方案的优势结合在一起。
+
 ---
 
 ## 模板属性表

shoulder-platform-common/shoulder-platform-archetype/src/main/resources/archetype-resources/CHANGELOG.MD

@@ -1,2 +1,22 @@
-# 更新记录
+# 版本变更记录
 
+
+## 1.1 （plaing）
+
+- xx
+    - xxx
+    - xxx
+
+- xx
+    - xxx
+    - xxx
+
+## 1.0 （202 年  月  日）
+
+- xx
+    - xxx
+    - xxx
+
+- xx
+    - xxx
+    - xxx

shoulder-platform-common/shoulder-platform-archetype/src/main/resources/archetype-resources/__rootArtifactId__-infrastructure/__rootArtifactId__-cache/pom.xml

@@ -11,4 +11,6 @@
 
     <description>缓存相关接口定义</description>
 
+    <!--有些 DDD shij实践将这些定义在领域层，但为了更方便扩展，将这些接口抽出，若更换，则只继承该模块进行改造即可-->
+
 </project>

shoulder-platform-common/shoulder-platform-archetype/src/main/resources/archetype-resources/__rootArtifactId__-provider/src/main/java/provider/controller/package-info.java

@@ -1,4 +1,4 @@
 /**
- * 给其他服务提供服务的实现
+ * 给其他服务提供服务的实现，有的系统可能还会分为 rest / rpc
  */
 package ${package}.provider.controller;

shoulder-platform-common/shoulder-platform-archetype/src/main/resources/archetype-resources/__rootArtifactId__-reference/__rootArtifactId__-reference-adaptor/pom.xml

@@ -15,7 +15,7 @@
 
     <dependencies>
 
-        <!-- xxx 应用 -->
+        <!-- xxx 应用 SDK -->
         <dependency>
             <groupId>${groupId}</groupId>
             <artifactId>${rootArtifactId}-reference-xxx</artifactId>

shoulder-platform-common/shoulder-platform-archetype/src/main/resources/archetype-resources/__rootArtifactId__-reference/__rootArtifactId__-reference-xxx/pom.xml

@@ -11,8 +11,9 @@
 
     <description>调用 xxx 应用提供的接口</description>
 
-    <!-- 该模块通常仅仅是继承 提供方提供的 dto/api 以屏蔽外部包路径，为可选模块，
-    若服务提供方未提供 DTO、Api 定义则在该模块放置 API、DTO、枚举等 -->
+    <!-- （可选）若服务提供方未提供sdk 甚至Api、DTO、枚举等定义，则在该模块放置
+    若服务提供方提供了sdk，如 feign-client 则通常不需要该模块。
+     -->
 
     <dependencies>
 

shoulder-platform-common/shoulder-platform-archetype/src/main/resources/archetype-resources/__rootArtifactId__-reference/__rootArtifactId__-reference-xxx/src/main/java/reference/api/DemoService.java

@@ -0,0 +1,28 @@
+#set( $symbol_pound = '#' )
+#set( $symbol_dollar = '$' )
+#set( $symbol_escape = '\' )
+package ${package}.api;
+
+import org.shoulder.core.dto.response.RestResult;
+
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.PathParam;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+
+/**
+ * demo 服务的接口
+ *
+ * @author ${author}
+ */
+public interface DemoService {
+
+    /**
+     * test
+     *
+     * @return BaseResult
+     */
+    RestResult configItem(String key);
+
+}

shoulder-platform-common/shoulder-platform-archetype/src/main/resources/archetype-resources/__rootArtifactId__-reference/__rootArtifactId__-reference-xxx/src/main/java/reference/api/dto/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * 这里定义传输对象
+ */
+package ${package}.dto;

shoulder-platform-common/shoulder-platform-archetype/src/main/resources/archetype-resources/__rootArtifactId__-reference/__rootArtifactId__-reference-xxx/src/main/java/reference/api/dto/param/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * 这里定义接口入参对象
+ */
+package ${package}.dto.param;

shoulder-platform-common/shoulder-platform-archetype/src/main/resources/archetype-resources/__rootArtifactId__-reference/__rootArtifactId__-reference-xxx/src/main/java/reference/api/dto/result/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * 这里定义接口返回值对象
+ */
+package ${package}.dto.result;

shoulder-platform-common/shoulder-platform-archetype/src/main/resources/archetype-resources/__rootArtifactId__-reference/__rootArtifactId__-reference-xxx/src/main/java/reference/api/impl/DemoServiceClient.java

@@ -0,0 +1,25 @@
+#set( $symbol_pound = '#' )
+#set( $symbol_dollar = '$' )
+#set( $symbol_escape = '\' )
+package ${package}.api.impl;
+
+import org.shoulder.core.dto.response.RestResult;
+import ${package}.api.DemoService;
+
+/**
+ * 实现调用 DemoService
+ *
+ * @author ${author}
+ */
+public class DemoServiceClient implements DemoService {
+
+    /**
+     * configItem
+     *
+     * @return BaseResult
+     */
+    public RestResult configItem(String key) {
+        System.out.print("假装调了一次接口");
+    }
+
+}

shoulder-platform-common/shoulder-platform-archetype/src/main/resources/archetype-resources/__rootArtifactId__-reference/__rootArtifactId__-reference-xxx/src/main/java/reference/package-info.java

@@ -1,4 +1,4 @@
 /**
- * 具体某个应用的接口
+ * 与外部接口交互
  */
 package ${package}.reference;

shoulder-platform-common/shoulder-platform-archetype/src/main/resources/archetype-resources/__rootArtifactId__-web/src/main/java/web/vo/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * 这里定义传输对象，一般 DDD 实践中，一个请求对应两个 VO（param、result），便于维护，但可能带来类爆炸
+ */
+package ${package}.vo;

shoulder-platform-common/shoulder-platform-archetype/src/main/resources/archetype-resources/__rootArtifactId__-web/src/main/java/web/vo/param/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * 这里定义视图层入参对象
+ */
+package ${package}.vo.param;

shoulder-platform-common/shoulder-platform-archetype/src/main/resources/archetype-resources/__rootArtifactId__-web/src/main/java/web/vo/result/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * 这里定义视图层返回值对象
+ */
+package ${package}.vo.result;