1.14.俯瞰:配置地图
Last updated
Last updated
俯瞰江流青一带,坐看山色碧千寻。——蔡戡《陪宪使登榕溪阁》
项目地址:https://github.com/silentbalanceyh/vertx-zero-example/(子项目:up-native)
完整地图文件:Version 1.1
本文不讲解任何和Zero Extension相关的详细配置信息,那是另外一个故事,而本文中使用的配置地图部分以1.1版为主,可能和本系列教程中的内容不一致,主要是写本文时Zero Extension最新版还在开发中。
虽然Zero框架名字叫“零”,没有任何配置也是可启动的,但往往在真实项目中要真正零配置几乎是不太可能,只是设计时如何让配置的量减到最低,又或者说让配置本身变得简单而实用且易于扩展,让开发人员压力更小,这才是目的。
Zero的基础配置规范如下:
只有两种配置文件名,.json
和.yml
(yaml)格式。
主配置从src/main/resources
中的vertx.yml
文件作入口。
选择yml
文件是因为我在设计和开发Zero之前一直使用的是Spring Boot,而Zero框架的很多设计思路也是基于它而来,正因为在实际项目开发中看到了痛点、难点 ,所以一切从简,同时使得曾经用过Spring Boot的开发者可以很流畅过渡。
Zero预定义了基础框架的部分结构,该结构存储在vertx-co
项目中,且它的完整结构如下图:
Zero中的核心配置主要分两部分:
内部配置:内部配置在您提供了相关配置后会被合并(内部配置 = 默认配置 + 您的配置
)。
Lime配置:Lime配置主要由用户提供,提供该配置后,Zero会去扫描所有关联的节点,最终生成唯一的一份JsonObject
——全环境统一配置。
从上述配置信息可知,除了内部配置以外,其他Lime相关配置的根节点不能出现重复(重复会覆盖),本章的任务就是带着您看看Zero中目前的Lime有些什么样的魑魅魍魉。
异常配置包含两个文件:
vertx-error.yml
Lime配置
错误代码异常堆栈信息定义模板,以E打头。
vertx-readible.yml
独立文件
直接读取,和vertx-error.yml代码绑定。
之前讲解容错部分已经解释过这两个文件的用法,此处就不详细解释它的基本结构了,您可以将这两个文件理解成两个哈希表,针对某一个错误代码code
而言:
插件配置位于vertx-inject.yml
文件中,默认插件配置只包含了日志记录器:
除此,您还可以增加以下配置:
如果您编写了自定义的Infix,那么上述配置中只要不重名即可。
Resolver配置是Zero中的特殊配置,它的基础内容位于vertx-resolver.yml
文件中,默认内容如:
上述配置在之前的文件中讲解过,按文件结构,它处理的MIME如下表格:
(默认)
DefaultResolver
处理不带MIME的请求。
application/json
JsonResolver
Json数据处理。
application/octet-stream
BufferResolver
二进制数据处理。
application/x-www-form-urlencoded
XFormResolver
多媒体表单处理。
multipart/form-data
FormResolver
带上传功能请求处理。
服务器配置位于vertx-server.yml
文件中,默认的配置如下:
注意这里支持的服务器数量是多个,server
节点是一个数组,而不是单个服务器,主要是为微服务环境量身打造的,而此处的type
节点是读者必须要理解的节点
http
Http服务器,常用的RESTful容器。
HttpServerOptions
api
微服务模式中的Api Gateway服务。
HttpServerOptions
ipc
微服务模式中的Service服务,此时根据名称进行连接。
HttpServerOptions
sock
「保留」WebSocket专用服务。
rx
「保留」Rx模式下的Http服务器(类名不同。
「保留」为设计了此扩展但还未实现的部分,后续版本会逐渐扩展。
主配置位于vertx.yml
文件中,默认的配置内容如:
Zero中设计的完整Vert.x部分的配置结构图如下:
整个结构包含了两个维度处理RESTful的配置:
您是使用Vert.x的集群模式还是单点模式(实战可知,单点模式已经够用了)。
您是使用Zero中的单机模式还是微服务模式(微服务模式下需配置ipc和api两种服务器)。
主配置的Vert.x实例的每个节点options
对应的就是VertxOptions
数据结构。
本章节中所有的配置都包含了固定的文件名,这是Zero内置的固定配置,如果您想要拓展自己的配置只能走Lime,这也是本文第一章节称为内部配置的原因,汇总如下:
vertx.yml
独立文件
主配置文件,Vertx实例专用配置。
vertx-inject.yml
Lime配置
插件Infix专用配置文件。
vertx-server.yml
Lime配置
HTTP服务器专用配置。
vertx-resolver.yml
独立文件
MIME解析器(可扩展)。
vertx-error.yml
Lime配置
异常代码表。
vertx-readible.yml
独立文件
业务异常信息配置。
lime的翻译为石灰,石灰遇水就会爆发出能量,在系统中它表示所有的插件遇到了Zero后就可发挥出它的最大能量,对所有lime配置而言,Zero就是:生命之源。
Lime配置是Zero中最灵活的配置,您可以使用一个文件来配置所有内容,也可以使用多个文件来分开配置,不论多少文件,其文件名都是按照lime
中定义的子文件进行汇总,假设您定义了如下片段:
那么Zero会将vertx-x1.yml、vertx-x2.yml、vertx-x3.yml
三个文件内容合并到一起生成一个唯一的JsonObject配置,这种做法唯一的限制就是Lime针对不同功能时配置的键名必须唯一。
此处提供两套完整的文件规范(不包含主配置)。
按功能拆分
vertx-jooq.yml
Jooq主库配置、历史库配置。
vertx-session.yml
会话专用配置。
vertx-redis.yml
Redis相关配置(zero-ifx-redis)。
vertx-trash.yml
历史库备份功能专用配置(zero-ifx-history)。
vertx-es.yml
ElasticSearch专用配置(zero-ifx-es)。
vertx-neo4j.yml
Neo4j图库配置(zero-ifx-neo4j)。
vertx-secure.yml
安全相关配置(包括跨域配置)。
vertx-shell.yml
DevOps命令行专用配置(zero-ifx-shell)。
vertx-router.yml
动态路由启用专用配置(zero-jet)。
vertx-deployment.yml
Verticle部署专用配置。
vertx-init.yml
初始化专用配置。
vertx-extension.yml
Zero Extension模块核心配置。
vertx-job.yml
后台任务专用配置。
vertx-cache.yml
L1、L2、L3缓存专用配置。
vertx-debug.yml
调试专用配置。
vertx-shared.yml
SharedData专用配置。
vertx-sms.yml
阿里短信服务配置(zero-ifx-sms)。
vertx-iqiy.yml
爱奇艺视频服务配置(zero-ifx-iqiy)。
vertx-feign.yml
Feign客户端配置(zero-ifx-feign)。
vertx-excel.yml
Excel导入导出专用配置(zero-ifx-excel)。
vertx-rpc.yml
微服务专用配置(zero-iproxy)。
vertx-etcd.yml
微服务ETCD专用配置。
最佳实践
最佳实践主要来自于生产环境中的基础文件合并,上述文件过多,如果不做一定程度的压缩,那么对开发人员而言挺繁琐的,压缩文件符合几个基本原则:
复杂配置和独立功能放到一个独立文件中以方便直接更改。
常用固定配置基本只需要配置一次,修改后就不变了,放到一起。
生产部署和开发不同的文件放到一起,每次部署之前统一修改,也方便DevOps脚本。
压缩过后的文件结构如:
vertx-excel.yml
Excel导入导出专用定义,内容比较长,独立文件。
vertx-cache.yml
L1、L2、L3三级缓存的基础配置(目前只支持L1,Redis)。
vertx-shell.yml
DevOps专用配置。
vertx-secure.yml
维持不变。
vertx-rpc.yml
微服务专用配置(zero-iproxy),原-rpc, -etcd
vertx-extention.yml
原-init, -extension,-job, -shared, -session
配置。
vertx-jet.yml
原-router, -deployment
配置。
vertx-jooq.yml
原-jooq, -redis, -trash, -es, -neo4j
配置,以及跨域。
vertx-tp.yml
原-sms, -iqiy
相关配置。
简单说明一下:
vertx-jooq.yml
是在切换环境时改动最大的一个文件,这样的结构做环境迁移几乎不需要去改动其他配置文件,仅修改vertx-jooq.yml
即可,因为它包含了所有和Zero相关的集成部分。
单点模式下vertx-tp.yml、vertx-rpc.yml
是不用配置的文件。
vertx-jet.yml
主控Verticle数量,可做简单模式下的性能调优。
所以最终形成的配置文件结构如:
截图中目录配置表如下:
cab
X_MODULE
中和前端页面绑定的动态配置。
codex
Zero验证模块专用的接口验证配置(@Codex)。
keys
安全专用jceks文件目录以及其他签名文件目录。
plugin
Zero Extension模块专用文件目录。
pojo
旧系统映射层专用配置文件目录。
init
初始化Excel模板数据存储位置,包含所有OOB数据文件。
runtime
运行时的静态配置(可自由处理)。
以上目录中除init
和runtime
是可自定义的,其他几个目录几乎是固定的,而且不会重复以及冲突。init
目录中包含了系统初始化的所有配置数据,它是产品 第一个版本的OOB(Out-Of-Box)数据,您可以直接使用该目录的数据重置系统,等价于恢复出厂;runtime
目录中包含了运行时的各种配置数据,如DevOps、动态建模临时文件、数据模板、特殊插件、测试框架Mock配置等所有和运行相关的配置文件都在此目录中。
接下来按功能来看看各部分的详细配置,瞅瞅这张地图,详细配置图可参考:
provider是主业务数据库配置,如果是动态建模方式,它表示平台数据库,一般用DB_ORIGIN_X
或其他,若不启用动态建模,则该数据库就是核心业务数据库。
orbit是历史记录数据库,若启用了删除备份功能,则使用该数据库存储被物理删除的数据。
此处需要说明的是会话存储器的核心配置,该会话存储器主要分三类:
LOCAL
io.vertx.ext.web.sstore.LocalSessionStore
CLUSTER
io.vertx.ext.web.sstore.ClusteredSessionStore
DEFINE
io.vertx.tp.plugin.redis.RedisStore或其他
上述配置在配置了session
节点时自动生效,而options
配置主要针对category = DEFINE
类型,这种情况需开发人员自己提供自定义的SessionStore实现,该实现可参考RedisStore
的代码。
zero-ifx-redis
zero-ifx-history
zero-ifx-es
zero-ifx-neo4j
Neo4j一般支持三种连接协议:
bolt
7687
dbms.connector.bolt
http
7474
dbms.connector.http
https
7473
dbms.connector.https
这部分配置在安全章节已经讲解,此处就不再过多说明。
zero-ifx-shell
注意图中红色部分,还有隐藏的配置,但这些配置太过复杂,在讲解Zero中的命令行框架时会单独讲解所有详细配置。
zero-jet
该文件合并表格中的vertx-router.yml
和vertx-deployment.yml
。
这份配置有几点说明:
router主控动态路由配置
Agent组件线程数就是32。
Worker组件线程数为Agent x 4 = 128
,Worker依靠Agent发布。
deployment主控静态路由配置
Agent组件线程数为32。
Worker组件线程数为128。
后续版本中会将router中的Worker标准化,instances是多少就发布多少,这是曾经的一次失误开发引起的问题。
该文件合并表格中的vertx-init.yml
和vertx-extension.yml
。
这部分配置和前文提到过的插件相关,启用了CRUD项目过后,配置本身就变得比较复杂了,特别是Auditor的exclude部分,若不启用CRUD则这部分配置会简单很多,主要目的是开启Zero Extension中的职责模块、数据域等功能,CRUD模块会在Zero Extension中单独介绍。
这部分配置会在任务系统章节单独说明。
直接查看上述注释部分,目前系统只支持Redis的L1级别的缓存信息。
0.8.0之后这部分配置有所变化,如:
只用于调试,生产环境部分日志会自动关闭。
rest.url.detect
web.uri.detecting
true
是否打开Uri的Detect日志,若打开则打印计算日志。
job.boot
job.booting
false
是否打印启动Job的日志。
jooq.condition
jooq.condition
false
是否打印Jooq的SQL底层条件监控日志。
jooq.password
password.hidden
false
是否在后台日志隐藏Jooq密码(防服务端盗窃)。
excel.range
excel.ranging
false
是否开启Excel的区域扫描日志。
crud.dao.file
crud.dao.file
false
是否打开IxDao的文件专用日志。
x
stack.tracing
false
是否打印部分底层异常。
该文件合并表格中的vertx-shared.yml, vertx-feign.yml, vertx-iqiy.yml, vertx-sms.yml
。
zero-ifx-feign, zero-ifx-iqiy, zero-ifx-sms
该文件中主要包含了第三方的详细配置,而vertx-shared.yml
配置其实放在哪个文件中都不影响整体,至于Feign, AliSms, IQiy这些第三方都是比较特殊的第三方集成,此处不提供示例。
zero-ifx-excel
0.8.0之后这部分配置有所变化,如:
Zero中在处理Excel模板时,支持很复杂的Excel模板,同时也支持复杂的风格渲染,如上边片段中pen
配置的是蓝色风格:
支持JsonArray的分离和合并导入导出。
支持Formula表达式以及外联文件表达式实现目录下的Excel链接。
2003和2007双格式支持。
支持单元格直接从文件读取序列化成JsonArray或JsonObject操作,JSON:
前缀。
支持单元格中的引用值读取,跨表导入导出。
详细功能在讲解插件时再举例说明。
该文件合并表格中的vertx-rpc.yml、vertx-etcd.yml
。
zero-iproxy
最后一份配置比较复杂,和微服务相关。
rpc
gRpc完整配置,做微服务之间服务通讯专用。
circuit
微服务中熔断专用配置。
etcd
微服务中服务配置中心Etcd相关配置(可支持集群配置中心)。
本章节带您领略了整个Zero框架中的所有配置,详细的配置图可参考本文最开始的配置地图专用链接下载该图(2.8M),后续更新会有新版本的配置完整地图。这些配置中某些配置部分是还没讲解的章节,而大部分都是已经讲解过的章节,有关配置的细节只能读者自己在学习过程去体会。