应用接口文档

Api Document Url : /doc.html

一、模块说明

二、开发 SpringBoot 应用

依赖对应模块

（一）快速开发 SpringBoot 应用

全局说明

• 统一注入io.gitee.zhangbinhub.acp.boot.log.LogAdapter进行日志记录

1. 开发说明

• （1）参考 example/testspringboot
• （2）依赖 acp-spring-boot-starter
• （3）yml配置文件中增加数据源配置（单数据源或多数据源），数据库操作遵循 spring-data-jpa 标准，使用 hibernate 进行实例化
• （4）单数据源应用的话无需增加额外配置类，正常编写service、repo、entity即可
• （5）多数据源应用需要增加对应每个数据源的 Jpa 配置类，并创建对应数据源的 repo、entity 包，之后再在对应包中编写 repo 和 entity
• （6）定时任务参考 example/testspringboot 模块io.gitee.zhangbinhub.acp.test.application.task.Task1，继承 io.gitee.zhangbinhub.acp.boot.base.BaseSpringBootScheduledTask 类，并在 yml 配置文件中增加对应执行规则
• （7）自定义系统初始化任务，新增任务类，实现io.gitee.zhangbinhub.acp.boot.init.AcpInitialization接口
• （8）自定义可控制监听器，新增监听器类，实现io.gitee.zhangbinhub.acp.boot.listener.AcpListener接口
• （9）参考 example/testspringboot 模块，io.gitee.zhangbinhub.acp.test.application.test包中有 tcp、udp 服务端开发demo，并在 application-dev.xml 中增加相应配置
• （10）如有需要，可选择引入 acp-core-file、acp-spring-boot-starter-ftp 等包
• （11）开发TCP服务端：自定义报文处理Bean，继承io.gitee.zhangbinhub.acp.boot.socket.base.TcpServerHandle ；自定义粘包拆包解码器Bean，继承io.netty.handler.codec.ByteToMessageDecoder
• （12）开发UDP服务端：自定义报文处理Bean，继承io.gitee.zhangbinhub.acp.boot.socket.base.UdpServerHandle
• （13）开发TCP/UDP客户端 参考TestClient
• （14）开发FTP服务端：自定义用户工厂Bean，实现io.gitee.zhangbinhub.acp.core.ftp.user.UserFactory
• （15）开发FTP/SFTP客户端 参考TestClient
• （16）默认是基于servlet的MVC模式，如需开发基于webflux的应用，启动方法设置webApplicationType即可，参考 example/testreactive

@SpringBootApplication
class TestReactiveApplication

fun main(args: Array<String>) {
    SpringApplication(TestReactiveApplication::class.java).apply {
        this.webApplicationType = WebApplicationType.REACTIVE
        this.run(*args)
    }
}

• （17）基于servlet的应用,开发WebSocket服务端：自定义WebSocket Endpoint，继承io.gitee.zhangbinhub.acp.boot.websocket.servlet.AcpWebSocketServerServlet ；参考TestWebSocketServerServlet
• （18）基于webflux的应用,开发WebSocket服务端：自定义WebSocket Endpoint，继承io.gitee.zhangbinhub.acp.boot.websocket.reactive.AcpWebSocketServerReactive ；参考TestWebSocketServerReactive
• （19）基于servlet的应用,开发WebSocket客户端：自定义WebSocket Client，继承io.gitee.zhangbinhub.acp.boot.websocket.servlet.AcpWebSocketClient ；参考TestClient
• （20）基于webflux的应用,开发WebSocket客户端：自定义WebSocket Client，继承io.gitee.zhangbinhub.acp.boot.websocket.reactive.AcpWebSocketClient ；参考TestClient
• （21）自定义web异常处理
  • 自定义类实现接口io.gitee.zhangbinhub.acp.boot.exceptions.AcpWebExceptionHandler
  • 实现方法identify，用于判断指定的异常是否需要进行处理
  • 实现方法handle，将异常信息进行转换
  • 实现方法getOrder，设置异常处理类的调用顺序
  • 自定义类注册为Bean

2. 配置说明

• 定制开发的 api 接口，开启文档

springdoc:
  api-docs:
    enabled: true

• 配置定时任务

acp:
  schedule:
    cron:
      task1: 0 0/1 * * * ?

key-value 形式（可配置多个），其中 task1 为任务的 beanName；0 0/1 * * * ? 为定时执行规则cron表达式。

• tcp 服务端

acp:
  tcp-server:
    listeners:
      - name: testSocket             #监听服务名称
        enabled: true                #是否启用，默认false
        keepAlive: false             #是否为长连接，默认false；TCP服务有效
        readerIdleTime: 10000        #读等待时间单位毫秒，默认10000；TCP服务有效
        writerIdleTime: 0            #写等待时间单位毫秒，默认0；TCP服务有效
        idleTime: 0                  #连接进入空闲状态的等待时间单位毫秒，默认0；TCP服务有效
        messageDecoder: ""           #粘包拆包解码器类全限定名称，默认不设置；TCP服务有效
        threadNumber: 100            #接收报文处理的最大线程数，为0或不设置则使用系统默认线程数；TCP服务有效
        hex: false                   #接收报文是否是十六进制机器码，默认false
        port: 9999                   #监听端口号
        handleBean: testTcpHandle    #报文接收处理 Bean 的 Name
        responsible: true            #报文是否需要进行原路响应，默认true
        charset: gbk                 #服务使用字符集，为空或不设置则系统默认字符集

• udp 服务端

acp:
  udp-server:
    listeners:
      - name: testSocket             #监听服务名称
        enabled: true                #是否启用，默认false
        hex: false                   #接收报文是否是十六进制机器码，默认false
        port: 9999                   #监听端口号
        handleBean: testUdpHandle    #报文接收处理 Bean 的 Name
        responsible: true            #报文是否需要进行原路响应，默认true
        charset: gbk

• ftp 服务端

acp:
  ftp-server:
    listeners:
      - name: "测试ftp服务器"                                                 #服务名车鞥
        enabled: true                                                        #可空，是否启用，默认false
        port: 221                                                            #服务端口号
        pwd-encrypt-mode: MD5                                                #可空，用户密码加密方式（支持MD5、SHA1、SHA256），默认MD5
        login-failure-delay: 30                                              #可空，默认30
        max-login-failures: 20                                               #可空，默认20
        max-logins: 10                                                       #可空，默认10
        max-anonymous-logins: 20                                             #可空，默认20
        max-threads: 10                                                      #可空，默认10
        default-home-directory: "abs:D:\\个人\\测试ftp"                       #默认根路径
        anonymous-login-enabled: false                                       #可空，是否允许匿名用户登录，默认false
        anonymous-write-permission: false                                    #可空，是否允许匿名用户写操作，默认false
        user-factory-class: testUserFactory                                  #用户工厂 Bean 的 Name

• 配置项附录

（二）启停 SpringBoot 应用

• 启停脚本(Linux) server.sh，根据实际情况修改第2行 APP_NAME 和第3行 JVM_PARAM 的值即可，和 SpringBoot 应用的 .jar 放在同一路径下
• 启停脚本(windows) server.bat，根据实际情况修改第1行末尾需要执行的 jar 名称，和SpringBoot应用的 .jar 放在同一路径下
• Linux 命令：

三、开发 SpringCloud 应用

demo 位于 example/spring-cloud

（一）基础中间件环境搭建

• 必要基础中间件包括：nacos、redis、redisinsight、zookeeper、kafka、kafka-eagle、zipkin
• 可选基础中间件包括：elasticsearch、logstash、kibana
• 参考对应的docker-compose文件

（二）组件开发

全局说明

• 统一注入io.gitee.zhangbinhub.acp.boot.log.LogAdapter进行日志记录

1. 可视化监控

• example/spring-cloud/admin-server
• （1）依赖 acp-spring-cloud-starter
• （2）无需改动代码
• （3）修改 yml 配置即可

2. 网关服务

• example/spring-cloud/gateway-server
• （1）需自定义限流策略（需依赖 Redis）
• （2）修改 yml 进行路由配置；若没有 Redis 请不要配置限流策略

3. 认证服务

• example/spring-cloud/oauth-server
• （1）依赖
  • acp-spring-cloud-starter-resource-server
  • org.springframework.security:spring-security-oauth2-authorization-server
  • org.springframework.boot:spring-boot-starter-data-redis
• （2）入口类增加注解 @AcpCloudAtomApplication
• （3）基于 spring-security-oauth2-authorization-server 深度定制 grant_type=password 模式
• （4）token 存储于 Redis，user 及 client 信息可扩展配置

查看认证过程

4. 日志服务（依赖 kafka）

• （1）依赖 acp-spring-cloud-starter-resource-server
• （2）入口类增加注解 @AcpCloudResourceServerApplication
• （3）如需自定义日志消息处理，新增Bean实现 io.gitee.zhangbinhub.acp.cloud.log.consumer.LogProcess 接口，并且增加 @Primary 注解
• （4）根据各服务配置的日志类型（默认为"ALL"），在 logback-spring.xml 中参照 ALL 和 ALL-LOGSTASH 进行配置

• a. 配置两个 appender（一个输出到本地文件，一个输出到logstash；单独配置的目的是为了将不同类型的日志写入不同名称的文件并在elasticsearch中创建不同的索引）

• b. 之后再配置一个 logger （name属性为某个日志类型）,包含之前配置的两个 appender

• c. 强烈建议 logback-spring.xml 中配置的本地日志文件路径需与 yml 中的 logging.file.path 一致，方便统一管理
• （5）增加配置

  acp:
    cloud:
      log-server:
        enabled: true #是否开启日志服务

5. 原子服务

• （1）依赖 acp-spring-cloud-starter-resource-server
• （2）参考 四、开发 SpringBoot 应用
• （3）原子服务即 SpringBoot 应用，引入额外的 spring-cloud 包，并在 yml 中增加相应配置
• （4）参考 example/spring-cloud/hello、example/spring-cloud/world、example/spring-cloud/helloworld、example/spring-cloud/helloworld-reactive，入口类增加注解 @AcpCloudResourceServerApplication
• （5）进行日志服务配置

  acp:
    cloud:
      log-server:
        client:
          enabled: true #是否启用日志服务
          log-type: ALL #当前服务的日志类型，默认ALL，也自定义；自定义的类型需要在日志服务中参照ALL配置appender和logger
• （6）如有特殊需要不进行认证的url（例如"/customer"），则增加permit-all-path配置；如有需要进行认证的url（例如" /customer2" ），则增加security-path配置

  acp:
   cloud:
     resource-server:
       permit-all-path: 
         - /customer
       security-path:
         - /customer2
• （7）cloud:acp-spring-cloud-starter-resource-server中强制开启了Http Basic认证，保护/actuator接口
  • 认证用户名和密码使用acp.cloud.resource-server.client-id和acp.cloud.resource-server.client-secret配置项
  • 注册服务时需要将这两个配置项以元数据的形势user.name和user.password 上送给注册中心，以便监控系统能够正常访问/actuator（例如Spring Boot Admin）
• （8）如果原子服务不需要加入统一认证体系中，即不需要进行访问权限验证。
  • cloud:acp-spring-cloud-starter-resource-server依赖改为cloud:acp-spring-cloud-starter
  • 入口类注解AcpCloudResourceServerApplication改为AcpCloudAtomApplication

6. 自定义负载均衡策略

• （1）设置acp.cloud.loadbalancer.nacos.enabled=true开启SBA负载均衡器
• （2）自定义负载均衡过滤器 参考CustomerFilterA.java
• （3）自定义负载均衡算法 参考CustomerLoadBalancerAlgorithm.java

7. 服务间调用时Header传递

• （1）对需要传递的header key前缀进行配置acp.cloud.transmit-header.prefix
• （2）Servlet Feign调用时，会自动进行Authorization和指定前缀的header传递
• （3）远程token校验时，会自动进行指定前缀的header传递
• （4）使用自定义RestClient调用时传递header 参考HelloWorldController.java
• （5）使用自定义WebClient调用时传递header 参考HelloWorldController.java

8. Spring Security 过滤器调用链

WebAsyncManagerIntegrationFilter (1/22)
SecurityContextHolderFilter (2/22)
AuthorizationServerContextFilter (3/22)
HeaderWriterFilter (4/22)
CorsFilter (5/22)
LogoutFilter (6/22)
OAuth2AuthorizationServerMetadataEndpointFilter (7/22)
OAuth2AuthorizationEndpointFilter (8/22)
OAuth2DeviceVerificationEndpointFilter (9/22)
NimbusJwkSetEndpointFilter (10/22)
OAuth2ClientAuthenticationFilter (11/22)
BearerTokenAuthenticationFilter (12/22)
BasicAuthenticationFilter (13/22)
RequestCacheAwareFilter (14/22)
SecurityContextHolderAwareRequestFilter (15/22)
AnonymousAuthenticationFilter (16/22)
ExceptionTranslationFilter (17/22)
AuthorizationFilter (18/22)
OAuth2TokenEndpointFilter (19/22)
OAuth2TokenIntrospectionEndpointFilter (20/22)
OAuth2TokenRevocationEndpointFilter (21/22)
OAuth2DeviceAuthorizationEndpointFilter (22/22)

9. 配置附录

10. postman 测试

Acp-Test.openapi.3.0.json

四、Sentinel 动态数据源配置