{"id":13753848,"url":"https://github.com/lord-of-code/loc-framework","last_synced_at":"2025-04-09T09:08:05.225Z","repository":{"id":52638616,"uuid":"110830236","full_name":"lord-of-code/loc-framework","owner":"lord-of-code","description":"本项目是完全基于Spring Boot2和Springcloud Finchley所进行了开发的，目的是简化和统一公司内部使用微服务框架的使用方法","archived":false,"fork":false,"pushed_at":"2021-04-26T17:42:58.000Z","size":459,"stargazers_count":236,"open_issues_count":5,"forks_count":74,"subscribers_count":32,"default_branch":"master","last_synced_at":"2025-04-02T07:08:20.959Z","etag":null,"topics":["framework","microservice","spring-boot","spring-cloud","spring-mvc","springboot2"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lord-of-code.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-11-15T12:24:13.000Z","updated_at":"2025-01-03T21:46:38.000Z","dependencies_parsed_at":"2022-08-21T23:21:02.452Z","dependency_job_id":null,"html_url":"https://github.com/lord-of-code/loc-framework","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lord-of-code%2Floc-framework","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lord-of-code%2Floc-framework/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lord-of-code%2Floc-framework/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lord-of-code%2Floc-framework/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lord-of-code","download_url":"https://codeload.github.com/lord-of-code/loc-framework/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248008630,"owners_count":21032556,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["framework","microservice","spring-boot","spring-cloud","spring-mvc","springboot2"],"created_at":"2024-08-03T09:01:31.259Z","updated_at":"2025-04-09T09:08:05.198Z","avatar_url":"https://github.com/lord-of-code.png","language":"Java","funding_links":[],"categories":["spring-mvc"],"sub_categories":[],"readme":"[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.github.lord-of-code/loc-framework-build/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.github.lord-of-code/loc-framework-build)\n[![Build Status](https://travis-ci.org/lord-of-code/loc-framework.svg?branch=master)](https://travis-ci.org/lord-of-code/loc-framework)\n[![codecov](https://codecov.io/gh/lord-of-code/loc-framework/branch/master/graph/badge.svg)](https://codecov.io/gh/lord-of-code/loc-framework)\n\n# loc-framework\n本项目升级到基于Spring Boot 2.2版本和Spring Cloud Hoxton所进行了开发的\n目的是简化和统一微服务框架Spring Boot和Spring Cloud的使用方法\n\n## 目的\n通过一定的规则来统一编写各种依赖的Starter，方便在企业内部进行规则的统一，配置的统一，用法的统一，监控的统一，部署的统一\n方便再进一步的简化Spring Boot和Spring Cloud的使用，进一步分离通用框架代码和业务代码的耦合\n屏蔽一部分的基础内容，减少业务开发对底层基建处技术的了解， 更加专注于业务的开发\n\n\n## loc-framework 2.0 主要改动\n1. 升级基础依赖的Spring Boot 2.2 和 Spring Cloud Hoxton\n2. 使用springdoc-openapi代替springfox（springfox长期不进行更新，存在的一些bug得不到解决，需要的一些feature得不到开发）\n3. 升级logbook到2.0.0大版本，提供更多的日志记录的功能\n\n\n## springdoc-openapi对比于springfox的区别\n1. springdoc-openapi升级到了OpenAPI 3\n2. 注解使用了swagger-core的最新注解\n3. 支持了webflux的服务端\n4. 解决了一些重要bug\n\n## logbook需要注意的点\n1. logbook默认的DefaultSink记录日志是使用的trace级别，需要注意通过调整日志级别才能输出请求日志\n2. 需要排除一些不需要打印的路径(`/actuator/**`, `/v3/api-docs`, `/webjars/**`)\n\n\n## 记录访问日志默认规则\n1. request记录请求方法，请求头，请求参数（对于文件上传，和流上传不进行记录）\n2. response记录响应头，如果是正常返回则不记录响应体, 如果是status大于400的则记录响应体（对于返回文件和流不进行记录）\n\n\n## 通过统一变量来管理框架版本\n1. Maven 版本必须是 3.5.2 +\n2. pom.xml里面的properties的变量名称必须是revision\n3. 必须配合使用`flatten-maven-plugin`插件\n\n## 使用方式\n- pom.xml中加入parent\n```\n\u003cparent\u003e\n    \u003cgroupId\u003ecom.github.lord-of-code\u003c/groupId\u003e\n    \u003cartifactId\u003eloc-framework-starter-parent\u003c/artifactId\u003e\n    \u003cversion\u003e1.0.0-SNAPSHOT\u003c/version\u003e\n    \u003crelativePath/\u003e\n  \u003c/parent\u003e\n```\n\n- pom.xml加入相关插件(插件打出的uber.jar可以直接通过`java -jar uber.jar`来启动)\n```\n\u003cbuild\u003e\n  \u003cplugins\u003e\n    \u003cplugin\u003e\n      \u003cgroupId\u003eorg.springframework.boot\u003c/groupId\u003e\n      \u003cartifactId\u003espring-boot-maven-plugin\u003c/artifactId\u003e\n    \u003c/plugin\u003e\n    \u003cplugin\u003e\n      \u003cgroupId\u003eorg.apache.maven.plugins\u003c/groupId\u003e\n      \u003cartifactId\u003emaven-compiler-plugin\u003c/artifactId\u003e\n    \u003c/plugin\u003e\n  \u003c/plugins\u003e\n\u003c/build\u003e\n```\n\n## 提供的核心依赖(SpringBoot和SpringCloud)和辅助依赖\n\n- SpringBoot 2.0.4.RELEASE\n- SpringCloud Release Finchley.SR1\n- springfox-swagger2  2.9.0\n- log4jdbc 1.16\n- mybatis 3.4.6\n- mybatis-spring 1.3.2\n- mybatis-pagehelper 5.1.2\n- mybatis-plus 3.0.1\n- elasticjob 2.1.5\n- problem 0.24.0-RC.0\n- logbook 1.9.0\n- weixin-sdk 3.1.0\n\n## demo程序\n\n具体代码可以参考\n\n- [具体的demo](https://github.com/lord-of-code/loc-framework-demo)\n\n## 利用docker-compose启动基础依赖\n\n#### mysql\ndocker-compose -f docker/mysql.yml up -d\n端口为 3306\n\n#### redis\ndocker-compose -f docker/redis.yml up -d\n端口为 6379\n\n#### zk\ndocker-compose -f docker/zk.yml up -d\n端口为 2181, 2182, 2183\n\n#### kafka\ndocker-compose -f docker/kafka.yml up -d\n端口为 9092\n\n#### elasticsearch\ndocker-compose -f docker/es.yml up -d\n端口为 9200\n\n#### elasticjob\ndocker-compose -f docker/job.yml up -d\n端口为 8899 用户名 root 密码 root123\n\n#### zipkin-server\ndocker-compose -f docker/zipkin.yml up -d\n端口为 9411\n\n#### keycloak\ndocker-compose -f docker/keycloak.yml up -d\n端口为 7777\n\n#### influxdb\ndocker-compose -f docker/influxdb.yml up -d   #启动influxdb和grafana\n\n#### spring-cloud的基础环境搭建步骤\n[loc-cloud-component](https://github.com/lord-of-code/loc-cloud-component)\n里面主要包括了`eureka`、`config`、`sleuth`、`zuul`等基础组件的docker部署\n\n## 计划主要的starter\n- springmvc\n- logger\n- shutdown\n- jdbc\n- mybatis\n- okhttp\n- redis\n- kafka\n- keycloak\n- metrics\n- sleuth\n- weixin-sdk\n- ...\n\n\n\n## springmvc的starter的统一标准\n\n* 增加了http请求的accesslog的记录的Filter，记录的request和response的关键信息\n* 添加了ExceptionHandler，增加了异常情况的处理\n* 添加了统一的Response返回的数据格式，利用Problem来完成response的返回数据结构\n\n* 请求日志的相关配置\n```\nlogbook:\n  filter.enabled: true\n  format.style: json\n  exclude:\n    - /acutotor/**\n    - /admin/**\n  write:\n    category: com.loc.framework.accesslog\n    level: INFO\n    max-body-size: 2048\n```\n\n* 加入了cors跨域相关的Filter的配置\n```\nloc.web.springmvc.cors.enabled: false   #默认为false，默认不开启cors跨域的配置, 如果要开启，改成true\nloc.web.springmvc.cors.allowOrigins:    #默认为*, 可以通过数组进行添加\n  - ...\n  - ...\nloc.web.springmvc.cors.allowHeaders:    #默认为*, 可以通过数组进行添加\n  - ...\n  - ...\nloc.web.springmvc.cors.allowMethods:    #默认为*, 可以通过数组进行添加\n  - GET\n  - POST\n  - ...\nloc.web.springmvc.cors.allowExposeHeaders:   #默认没有，可以通过数组进行添加\n  - ...\n  - ...\n```\n\n* 加入了swagger的相关配置\n```\nloc.web.springmvc.swagger2.enabled: true  #默认为true, 表示是否开启swagger功能\n\nloc.web.springmvc.swagger2.apiinfo.title = \"project title\";\nloc.web.springmvc.swagger2.apiinfo.description = \"project description\";\nloc.web.springmvc.swagger2.apiinfo.version = \"v1\";\nloc.web.springmvc.swagger2.apiinfo.termsOfServiceUrl = \"https://github.com/lord-of-code/loc-framework\";\nloc.web.springmvc.swagger2.apiinfo.contactName = \"loc project\";\nloc.web.springmvc.swagger2.apiinfo.contactUrl = \"https://github.com/lord-of-code/loc-framework\";\nloc.web.springmvc.swagger2.apiinfo.contactEmail = \"dragonlong1986@126.com\";\nloc.web.springmvc.swagger2.apiinfo.license = \"project license\";\nloc.web.springmvc.swagger2.apiinfo.licenseUrl = \"https://github.com/lord-of-code/loc-framework\";\n\nloc.web.springmvc.swagger2.restapi.basePackage   #扫描的包路径，默认为all\nloc.web.springmvc.swagger2.restapi.paths         #扫描的paths，默认为all\n```\n\n## logger的starter统一日志标准(依赖logback日志框架)\n\n* 统一了logger的输出格式，主要考虑到后续的日志采集、统计、分析的统一\n```\n[%d{yyyy-MM-dd HH:mm:ss.SSS}] [%t] [%X{traceId}] %-5level %logger{50} - %msg%n\n```\n* 默认了logger的输出，分为console和file，默认的file存储在`./logs/loc.log`目录，可以通过配置文件`logging.file`进行修改\n* 日志按小时进行切割，切割后存放目录，默认是`./logs`目录，可以通过`logging.path`进行修改\n* 日志文件备份默认存放720小时(30天)\n\n\n## shutdown的starter来进行优雅的停机操作\n\n* 完成了tomcat的优雅停机策略\n\n```\nloc.tomcat.shutdown.enabled: true  #默认优雅停机策略是打开的\nloc.tomcat.shutdown.waitTime: 30   #默认30s的优雅停机等待时间，超过时间强行关闭\n```\n\n\n## jdbc的starter的统一标准\n\n* springboot从2.0开始使用HikariCP作为默认的DataSource\n关于HikariCP的配置可以参考[官方配置文档](https://github.com/brettwooldridge/HikariCP)\n\n程序启动的时候，通过实现`BeanFactoryPostProcessor`接口，来读取配置文件里面特定的字段来实现多数据源的加载\n```\nloc.dataSource:\n  firstDs:\n    username: root\n    password:\n    jdbcUrl: jdbc:mysql://127.0.0.1:3306/test\n    jdbcPool:\n      maximumPoolSize: 30\n      driverClassName: com.mysql.jdbc.Driver\n```\n因为都是通过手动进行读取的配置然后加载的，而没有走默认的`DataSourceAutoConfiguration`和`DataSourceTransactionManagerAutoConfiguration`\n所以在使用的时候`exclude`排出掉`DataSourceAutoConfiguration.class`和`DataSourceTransactionManagerAutoConfiguration.class`\n\n* 通过利用log4jdbc给HikariCP做相关的日志记录\n关于log4jdbc的配置可以参考[log4jdbc定义文件](https://github.com/lord-of-code/loc-framework/blob/master/loc-autoconfigure/src/main/resources/META-INF/spring-configuration-metadata.json)\n\n* 可以通过logging级别来控制数据库日志的输出\n```\nlogging.level.jdbc:\n  sqlonly: 'OFF'\n  sqltiming: INFO\n  audit: 'OFF'\n  resultset: 'OFF'\n  resultsettable: 'OFF'\n  connection: 'OFF'\n```\n\n## mybatis的starter的统一标准\n\n* mybatis的starter依赖了jdbc的starter, 所以一些配置是使用jdbc的配置\n\n* mybatis的starter同样支持多数据源的配置\n\n* mybatis的starter支持xml配置文件和注解的两种配置方式具体使用方式可以参考samples里面的:\n\n1. [mybatis-xml例子](https://github.com/lord-of-code/loc-framework/tree/master/loc-samples/loc-framework-mybatis-xml-sample)\n2. [mybatis-annotation例子](https://github.com/lord-of-code/loc-framework/tree/master/loc-samples/loc-framework-mybatis-annotation-sample)\n\n* myabtis的starter新增了和数据源相关的配置, 默认值都为null\n```\nloc.dataSource:\n  firstDs:\n    configLocation:            # datasource对应的mybatis-config.xml文件\n    basePackage:               # 接口所在的项目包\n    mapperLocations:           #\n    typeAliasesPackage:        #\n    executorType:              #\n    configurationProperties:   #\n    configuration:             #\n```\n\n* mybatis的starter新增了分页插件的相关的全局配置\n```\nloc.pagehelper:\n  helperDialect = \"mysql\";\n  offsetAsPageNum = false;\n  rowBoundsWithCount = false;\n  pageSizeZero = false;\n  reasonable = false;\n  params = \"pageNum=pageNum;pageSize=pageSize;count=countSql;reasonable=reasonable;pageSizeZero=pageSizeZero\";\n  supportMethodsArguments = false;\n  autoRuntimeDialect = false;\n  closeConn = true;\n```\n\n## okhttp的starter的统一标准\n\n* 加入了okhttp的client的构造，用于发起http请求，并且用于记录请求和回应的日志\n\n```\nloc.okhttp:\n  connectTimeout: 5000\n  readTimeout: 30000\n  writeTimeout: 30000\n  retryOnConnectionFailure: true\n  followRedirects: true\n  followSslRedirects: true\n  connection:\n    maxIdleConnections: 5\n    keepAliveDuration: 60000\n```\n\n## redis的starter的统一标准\n\n* 修改了一下cache manager的序列化方式, 把默认的value的序列化方式从jdk的序列化方式改成了json的序列化方式, 主要是为了方便redis存储数据的可读性\n* 重新封装了cache manager的使用方式，对于redis不可用的时候，还可以继续进行后续操作，认为缓存是可能出问题的，但是不会影响具体的业务逻辑操作\n\n* 下列事例配置参数\n```\nspring:\n  cache:\n    redis:\n      time-to-live: 100s  #默认的超时ttl时间\n      cache-names:\n        - redis-demo-1   #需要自定义的value的name\n        - redis-demo-2   #需要自定义的value的name\n  redis:\n    host: 127.0.0.1\n    port: 6379\n    timeout: 2s   #操作超时的情况，默认60s\n#  cluster.nodes:\n#    - 10.10.3.51:2001\n#    - 10.10.3.51:2002\n#    - 10.10.3.51:2003\n    lettuce:\n      pool:\n        max-active: 10\n        max-idle: 10\n        max-wait: \"1000\"\n\nloc.customCache:\n  redis-demo-1:         #对应上面 cache-names\n    time-to-live: 200s  #针对特殊的cache-name来进行自定义参数\n  redis-demo2-:\n    time-to-live: 300s  #针对特殊的cache-name来进行自定义参数\n```\n\n## kafka的starter的统一标准\n\n* 用kafka来作为主要的的消息队列\n* 统一定义k,v 使用 byte[] 数组来定义消息的key和value，方便统一处理\n* 给producer在发送的时候头里面加上了messageid、trace相关的信息、记录发送的日志和进行json转换，\n* 给consumer在处理消息错误的时候记录日志，处理完消息的时候记录日志，接受到消息的时候记录日志、处理trace的信息，对消息进行json转换等功能\n\n## elasticjob的starter的统一标准\n\n* 利用elasticjob组件完成分布式的调度\n* 提供注解来进行任务的配置\n\n## keycloak的starter的统一标准\n\n* keycloak是一个开源的统一认证的安全框架, 现在由于框架是基于springboot2进行开发的，keycloak-springboot-adapter的是基于springboot 1.x的版本来做的，所以出现了无法使用的情况，这个问题已经上报给keycloak官方了\n* 等待keycloak针对springboot2提供了adapter后会继续进行跟进此模块\n\n\n## metrics的starter的统一标准\n\n* SpringBoot2使用micro meter来作为连接底层的facade\n* 屏蔽掉了一些额外的没有意义的request path\n* 相关配置\n\n```\nmanagement:\n  endpoints.web.exposure.include:\n    - metrics\n  metrics:\n    export:                               #上报配置\n      influx:\n        uri: http://127.0.0.1:8086\n        step: 5s  //5秒上报一次\n        db: locMetrics\n    web:\n      server:\n        auto-time-requests: true\n        requests-metric-name: loc_http_requests\n      client:\n        max-uri-tags: 1000\n    binders:\n      logback:\n        enabled: false     #暂时关闭logback的metrics\n      uptime:\n        enabled: false     #暂时关闭uptime的metrics\n      files:\n        enabled: false     #暂时关闭files的metrics\n      integration:\n        enabled: false\n    enable:\n      tomcat: false        #暂时关闭tomcat的metrics\n      hikaricp: false      #暂时关闭hikaricp的metrics (SpringBoot2.0.0版本, 目前这个上报有bug，)\n      jdbc: false          #暂时关闭jdbc的metrics\n    distribution:\n      percentiles:\n        loc_http_requests:   #上报的分位数\n          - 0.5\n          - 0.75\n          - 0.9\n          - 0.95\n          - 0.99\n```\n\n## sleuth的starter的统一标准\n\n```\nspring:\n  sleuth:\n    sampler:\n      probability: 0\n    scheduled:\n      enabled: false\n    enabled: true\n```\n\n\n## eureka的starter的统一标准\n\n\n# 源码编译\n如果你想了解最新的一些功能和改动，可以通过编译源码来进行使用和测试\n\n* 如果使用mvn wrapper来进行编译,你需要确保使用的JDK版本为1.8以上\n```\n$ ./mvnw clean install\n```\n\n* 如果使用mvn来进行编译，你需要确保使用的mvn为Apache Maven v3.5.0 +\n```\n$ mvn clean install\n```\n\n* 如果使用windows系统，编译的时候需要跳过测试\n```\n$ mvn clean install -Dmaven.test.skip=true\n```\n\n\n# License\nLoc Framework is Open Source software released under the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flord-of-code%2Floc-framework","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flord-of-code%2Floc-framework","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flord-of-code%2Floc-framework/lists"}