1.14.俯瞰:配置地图
俯瞰江流青一带,坐看山色碧千寻。——蔡戡《陪宪使登榕溪阁》
项目地址: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的开发者可以很流畅过渡。
1.1. Zero配置结构
Zero预定义了基础框架的部分结构,该结构存储在vertx-co
项目中,且它的完整结构如下图:
Zero中的核心配置主要分两部分:
内部配置:内部配置在您提供了相关配置后会被合并(
内部配置 = 默认配置 + 您的配置
)。Lime配置:Lime配置主要由用户提供,提供该配置后,Zero会去扫描所有关联的节点,最终生成唯一的一份
JsonObject
——全环境统一配置。
从上述配置信息可知,除了内部配置以外,其他Lime相关配置的根节点不能出现重复(重复会覆盖),本章的任务就是带着您看看Zero中目前的Lime有些什么样的魑魅魍魉。
1.2. 异常配置
异常配置包含两个文件:
文件名 | Lime方式 | 含义 |
---|---|---|
vertx-error.yml | Lime配置 | 错误代码异常堆栈信息定义模板,以E打头。 |
vertx-readible.yml | 独立文件 | 直接读取,和vertx-error.yml代码绑定。 |
之前讲解容错部分已经解释过这两个文件的用法,此处就不详细解释它的基本结构了,您可以将这两个文件理解成两个哈希表,针对某一个错误代码code
而言:
配置地图
1.3. 插件配置
插件配置位于vertx-inject.yml
文件中,默认插件配置只包含了日志记录器:
除此,您还可以增加以下配置:
如果您编写了自定义的Infix,那么上述配置中只要不重名即可。
配置地图
1.4. Resolver配置
Resolver配置是Zero中的特殊配置,它的基础内容位于vertx-resolver.yml
文件中,默认内容如:
上述配置在之前的文件中讲解过,按文件结构,它处理的MIME如下表格:
MIME值 | 处理类 | 含义 |
---|---|---|
(默认) | DefaultResolver | 处理不带MIME的请求。 |
application/json | JsonResolver | Json数据处理。 |
application/octet-stream | BufferResolver | 二进制数据处理。 |
application/x-www-form-urlencoded | XFormResolver | 多媒体表单处理。 |
multipart/form-data | FormResolver | 带上传功能请求处理。 |
配置地图
1.5. 服务器配置
服务器配置位于vertx-server.yml
文件中,默认的配置如下:
注意这里支持的服务器数量是多个,server
节点是一个数组,而不是单个服务器,主要是为微服务环境量身打造的,而此处的type
节点是读者必须要理解的节点
type值 | 含义 | Options |
---|---|---|
http | Http服务器,常用的RESTful容器。 | HttpServerOptions |
api | 微服务模式中的Api Gateway服务。 | HttpServerOptions |
ipc | 微服务模式中的Service服务,此时根据名称进行连接。 | HttpServerOptions |
sock | 「保留」WebSocket专用服务。 | |
rx | 「保留」Rx模式下的Http服务器(类名不同。 |
「保留」为设计了此扩展但还未实现的部分,后续版本会逐渐扩展。
地图配置
1.6. 主配置
主配置位于vertx.yml
文件中,默认的配置内容如:
Zero中设计的完整Vert.x部分的配置结构图如下:
整个结构包含了两个维度处理RESTful的配置:
您是使用Vert.x的集群模式还是单点模式(实战可知,单点模式已经够用了)。
您是使用Zero中的单机模式还是微服务模式(微服务模式下需配置ipc和api两种服务器)。
主配置的Vert.x实例的每个节点options
对应的就是VertxOptions
数据结构。
本章节中所有的配置都包含了固定的文件名,这是Zero内置的固定配置,如果您想要拓展自己的配置只能走Lime,这也是本文第一章节称为内部配置的原因,汇总如下:
文件名 | 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配置
lime的翻译为石灰,石灰遇水就会爆发出能量,在系统中它表示所有的插件遇到了Zero后就可发挥出它的最大能量,对所有lime配置而言,Zero就是:生命之源。
Lime配置是Zero中最灵活的配置,您可以使用一个文件来配置所有内容,也可以使用多个文件来分开配置,不论多少文件,其文件名都是按照lime
中定义的子文件进行汇总,假设您定义了如下片段:
那么Zero会将vertx-x1.yml、vertx-x2.yml、vertx-x3.yml
三个文件内容合并到一起生成一个唯一的JsonObject配置,这种做法唯一的限制就是Lime针对不同功能时配置的键名必须唯一。
2.1. 常用规范
此处提供两套完整的文件规范(不包含主配置)。
按功能拆分
文件名 | 含义 |
---|---|
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),原 |
vertx-extention.yml | 原 |
vertx-jet.yml | 原 |
vertx-jooq.yml | 原 |
vertx-tp.yml | 原 |
简单说明一下:
vertx-jooq.yml
是在切换环境时改动最大的一个文件,这样的结构做环境迁移几乎不需要去改动其他配置文件,仅修改vertx-jooq.yml
即可,因为它包含了所有和Zero相关的集成部分。单点模式下
vertx-tp.yml、vertx-rpc.yml
是不用配置的文件。vertx-jet.yml
主控Verticle数量,可做简单模式下的性能调优。
所以最终形成的配置文件结构如:
截图中目录配置表如下:
目录名 | 含义 |
---|---|
cab |
|
codex | Zero验证模块专用的接口验证配置(@Codex)。 |
keys | 安全专用jceks文件目录以及其他签名文件目录。 |
plugin | Zero Extension模块专用文件目录。 |
pojo | 旧系统映射层专用配置文件目录。 |
init | 初始化Excel模板数据存储位置,包含所有OOB数据文件。 |
runtime | 运行时的静态配置(可自由处理)。 |
以上目录中除init
和runtime
是可自定义的,其他几个目录几乎是固定的,而且不会重复以及冲突。init
目录中包含了系统初始化的所有配置数据,它是产品 第一个版本的OOB(Out-Of-Box)数据,您可以直接使用该目录的数据重置系统,等价于恢复出厂;runtime
目录中包含了运行时的各种配置数据,如DevOps、动态建模临时文件、数据模板、特殊插件、测试框架Mock配置等所有和运行相关的配置文件都在此目录中。
接下来按功能来看看各部分的详细配置,瞅瞅这张地图,详细配置图可参考:
2.2. vertx-jooq.yml
配置地图
示例
说明
provider是主业务数据库配置,如果是动态建模方式,它表示平台数据库,一般用
DB_ORIGIN_X
或其他,若不启用动态建模,则该数据库就是核心业务数据库。orbit是历史记录数据库,若启用了删除备份功能,则使用该数据库存储被物理删除的数据。
2.3. vertx-session.yml
配置地图
示例
说明
此处需要说明的是会话存储器的核心配置,该会话存储器主要分三类:
category值 | 使用存储类 |
---|---|
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
的代码。
2.4. vertx-redis.yml
zero-ifx-redis
配置地图
示例
2.5. vertx-trash.yml
zero-ifx-history
配置地图
示例
2.6. vertx-es.yml
zero-ifx-es
配置地图
示例
2.7. vertx-neo4j.yml
zero-ifx-neo4j
配置地图
示例
说明
Neo4j一般支持三种连接协议:
协议名 | 默认端口 | 对应neo4j配置 |
---|---|---|
bolt | 7687 | dbms.connector.bolt |
http | 7474 | dbms.connector.http |
https | 7473 | dbms.connector.https |
2.8. vertx-secure.yml
配置地图
示例
这部分配置在安全章节已经讲解,此处就不再过多说明。
2.9. vertx-shell.yml
zero-ifx-shell
配置地图
示例
说明
注意图中红色部分,还有隐藏的配置,但这些配置太过复杂,在讲解Zero中的命令行框架时会单独讲解所有详细配置。
2.10. vertx-jet.yml
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是多少就发布多少,这是曾经的一次失误开发引起的问题。
2.11. vertx-extension.yml
该文件合并表格中的vertx-init.yml
和vertx-extension.yml
。
配置地图
示例
说明
这部分配置和前文提到过的插件相关,启用了CRUD项目过后,配置本身就变得比较复杂了,特别是Auditor的exclude部分,若不启用CRUD则这部分配置会简单很多,主要目的是开启Zero Extension中的职责模块、数据域等功能,CRUD模块会在Zero Extension中单独介绍。
2.12. vertx-job.yml
配置地图
示例
这部分配置会在任务系统章节单独说明。
2.13. vertx-cache.yml
配置地图
示例
直接查看上述注释部分,目前系统只支持Redis的L1级别的缓存信息。
2.14. vertx-debug.yml
配置地图
示例
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 | 是否打印部分底层异常。 |
2.15. vertx-tp.yml
该文件合并表格中的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这些第三方都是比较特殊的第三方集成,此处不提供示例。
2.16. vertx-excel.yml
zero-ifx-excel
配置地图
示例
0.8.0之后这部分配置有所变化,如:
说明
Zero中在处理Excel模板时,支持很复杂的Excel模板,同时也支持复杂的风格渲染,如上边片段中pen
配置的是蓝色风格:
支持JsonArray的分离和合并导入导出。
支持Formula表达式以及外联文件表达式实现目录下的Excel链接。
2003和2007双格式支持。
支持单元格直接从文件读取序列化成JsonArray或JsonObject操作,
JSON:
前缀。支持单元格中的引用值读取,跨表导入导出。
详细功能在讲解插件时再举例说明。
2.17. vertx-rpc.yml
该文件合并表格中的vertx-rpc.yml、vertx-etcd.yml
。
zero-iproxy
配置地图
说明
最后一份配置比较复杂,和微服务相关。
节点 | 含义 |
---|---|
rpc | gRpc完整配置,做微服务之间服务通讯专用。 |
circuit | 微服务中熔断专用配置。 |
etcd | 微服务中服务配置中心Etcd相关配置(可支持集群配置中心)。 |
「叄」小结
本章节带您领略了整个Zero框架中的所有配置,详细的配置图可参考本文最开始的配置地图专用链接下载该图(2.8M),后续更新会有新版本的配置完整地图。这些配置中某些配置部分是还没讲解的章节,而大部分都是已经讲解过的章节,有关配置的细节只能读者自己在学习过程去体会。
Last updated