在 基于 Docker 搭建开发环境（三）：链路追踪 等几篇文章中，D瓜哥分享了如何使用 Docker Compose 在本地搭建起来一套应用可观测性环境。感觉还不够好玩，毕竟正在在企业中，Kubernetes 已经是绝对的主流。要玩就玩最具挑战性的东西，玩最符合企业所需的技能和工具。所以，打算将上面那套简易玩具，按照企业级的要求，搬到 Kubernetes 上去。
如果想玩 Kubernetes，首先面临的一个问题就是 Kubernetes 集群的搭建。本来是一个非常简单的事情，但是由于众所周知的原因，变得非常具有挑战性。经过各种探索和多次试验，发现一种“离线”安装方式，感觉是一个不错的方式。
本方法是基于 Kubespray 的一种安装办法，Kubespray 是由 Kubernetes SIG 小组来负责维护的一整套安装方式。既可以支持在裸机环境上安装，也支持云上环境安装。而且，只需要简单几行可以复制粘贴的命令，即可完成安装工作。非常适合入门玩耍使用。
本安装方法所需的软件，D瓜哥都已经上传到 GitHub，如果需要下载，请移步： Kubespray-2.26.0 安装包大全。
搭建服务器集群 这里推荐使用 Vagrant 搭建集群。搭配 VirtualBox，只需要一个配置文件，就可以轻轻松松搭建一个 Linux 服务器集群。搭建集群的配置文件 Vagrantfile 如下：
# -*- mode: ruby -*- # vi: set ft=ruby : # @author D瓜哥 · https://www.diguage.com/ # All Vagrant configuration is done below. The "2" in Vagrant.configure # configures the configuration version (we support older styles for # backwards compatibility). Please don't change it unless you know what # you're doing. Vagrant.configure("2") do |config| # The most common configuration options are documented and commented below. # For a complete reference, please see the online documentation at # https://docs.vagrantup.com. # 三节点集群 (1..3).each do |i| config.vm.define "node#{i}" do |node| # Every Vagrant development environment requires a box. You can search for # boxes at https://vagrantcloud.com/search. node.vm.box = "ubuntu2404" # 设置虚拟机的主机名 node.vm.hostname = "node#{i}" config.vm.boot_timeout = 600 # Disable automatic box update checking. If you disable this, then # boxes will only be checked for updates when the user runs # `vagrant box outdated`. This is not recommended. # config.vm.box_check_update = false # Create a forwarded port mapping which allows access to a specific port # within the machine from a port on the host machine. In the example below, # accessing "localhost:8080" will access port 80 on the guest machine. # NOTE: This will enable public access to the opened port # config.vm.network "forwarded_port", guest: 80, host: 8080 # Create a forwarded port mapping which allows access to a specific port # within the machine from a port on the host machine and only allow access # via 127.0.0.1 to disable public access # config.vm.network "forwarded_port", guest: 80, host: 8080, host_ip: "127.0.0.1" # Create a private network, which allows host-only access to the machine # using a specific IP. # 设置虚拟机的IP node.vm.network "private_network", ip: "10.0.2.#{20+i}", auto_config: true # Create a public network, which generally matched to bridged network. # Bridged networks make the machine appear as another physical device on # your network. # config.vm.network "public_network" # Share an additional folder to the guest VM. The first argument is # the path on the host to the actual folder. The second argument is # the path on the guest to mount the folder. And the optional third # argument is a set of non-required options. # 设置主机与虚拟机的共享目录，根据需要开启 node.vm.synced_folder "/path/to/#{i}", "/data" # Disable the default share of the current code directory. Doing this # provides improved isolation between the vagrant box and your host # by making sure your Vagrantfile isn't accessible to the vagrant box. # If you use this you may want to enable additional shared subfolders as # shown above. # config.vm.synced_folder ".", "/vagrant", disabled: true # Provider-specific configuration so you can fine-tune various # backing providers for Vagrant. These expose provider-specific options. # Example for VirtualBox: node.vm.provider "virtualbox" do |vb| # 设置虚拟机的名称 # vb.name = "node#{i}" # if node.vm.hostname == "node1" # # Display the VirtualBox GUI when booting the machine # vb.gui = true # end # Customize the amount of memory on the VM: vb.memory = "6144" # 设置虚拟机的CPU个数 vb.cpus = 2 end # View the documentation for the provider you are using for more # information on available options. # Enable provisioning with a shell script. Additional provisioners such as # Ansible, Chef, Docker, Puppet and Salt are also available. Please see the # documentation for more information about their specific syntax and use. # config.vm.provision "shell", inline: <<-SHELL # sudo yum makecache --refresh # sudo yum install -y tcpdump # sudo yum install -y nc # sudo yum install -y net-tools # SHELL end end end
基于 Docker 搭建开发环境系列:
基于 Docker 搭建开发环境（一）：数据库+监控
基于 Docker 搭建开发环境（二）：EFK 日志套件
基于 Docker 搭建开发环境（三）：链路追踪
在上一篇文章 基于 Docker 搭建开发环境（一）：数据库+监控 和 基于 Docker 搭建开发环境（二）：EFK 日志套件 两篇文章中，分别介绍了“数据库+监控”和“EFK 日志套件”。这篇文章给大家分享一下如何在本地搭建起一套简单的分布式链路追踪。
在 AI 的帮助下，如同砍瓜切菜一样，非常迅速地就完成了 基于 Docker 搭建开发环境（二）：EFK 日志套件 的搭建。原以为搞这个也会分分钟的问题，结果应用的追踪数据一致无法正常发送到 Jaeger 中，各种改端口号都不行。后来，无意间看了 OpenTelemetry 的配置文档，增加了一个协议配置，全部流程竟然通了，非常神奇！
站在更高的视角去看，链路追踪其实是可观测性的一部分，包括上篇文章的日志，也是可观测性的一部分。日志、追踪、度量，三者是相辅相成的。
图 1. 可观测性 在 OpenTelemetry 出现之前，日志、追踪、度量是分离的，三者各各自为战。而 OpenTelemetry 的出现，则是试图将三者统一。目前 OpenTelemetry 是云原生架构中，最炙手可热的分布式链路追踪解决方案，它提供了一套相关标准，各个厂商可以在这套标准之上进行各种各样的组件开发，大家可以根据自己的需要，选择不同的组件，进行可插拔式的安装。
图 2. OpenTelemetry 的野心 在这篇文章中，链路追踪的解决方案选择的是 OpenTelemetry + OpenTelemetry Collector + Jaeger。
OpenTelemetry OpenTelemetry 并不需要在 Docker 中启动或者配置什么。在目前的架构中，Jaeger 是作为 OpenTelemetry 的一个实现来出现的。 OpenTelemetry 需要做的就是下载一个 Java Agent，执行 docker/config/opentelemetry/download-opentelemetry-agent.sh 脚本即可下载最新版的 Java Agent。在业务应用启动时，增加如下 JVM 参数：
基于 Docker 搭建开发环境系列:
基于 Docker 搭建开发环境（一）：数据库+监控
基于 Docker 搭建开发环境（二）：EFK 日志套件
基于 Docker 搭建开发环境（三）：链路追踪
在上一篇文章 基于 Docker 搭建开发环境（一）：数据库+监控 中，介绍了一下如何使用 Docker 搭建起 MySQL + NACOS + Prometheus + Grafana 集成数据库、注册中心+配置管理、监控的开发环境。这篇文章来介绍一下如何在原来的基础上接入 Elasticsearch + Fluentd + Kibana 套件，并且将 NACOS 的日志接入到 Elasticsearch 里。
Elasticsearch 由于 Elasticsearch 8+ 的版本修改了安全策略，不允许 Kibana 使用超级管理员 elastic 连接 Elasticsearch，这里选用 7.x 版本做演示。
还有一点需要提醒，在设置 Elasticsearch 的超级管理员 elastic 的账户密码时，如果密码是全部的阿拉伯数字，那么需要用双引号或者单引号括起来。
在测试中，还遇到一个磁盘过载导致的只读问题。解决方式如下：
curl -X GET "localhost:9200/_cat/allocation?v&pretty" 查看磁盘使用情况
解除只读状态
$ curl -X PUT "localhost:9200/test/_settings" -H 'Content-Type: application/json' -d' { "index.blocks.read_only_allow_delete": null } '
基于 Docker 搭建开发环境系列:
基于 Docker 搭建开发环境（一）：数据库+监控
基于 Docker 搭建开发环境（二）：EFK 日志套件
基于 Docker 搭建开发环境（三）：链路追踪
去年，很多同事要换 Mac 本，所以，写了 新 Mac 安装软件脚本，方便大家一键换机。最近想玩一下 Spring Cloud 以及相关周边的部署、监控等开源解决方案。由于组件众多及为了便于迁移和共享，计划基于 Docker 及 Docker Compose 搭建一套相关的开发环境。记录一下，方便有相同需求的朋友借鉴。
最新版的 Docker 在下载镜像时，会先访问一下 Docker 的官方站点。由于国内众所周知的网络情况，访问 Docker 官方站点总失败。所以，即使配置了国内 Docker 镜像站点也会失败。只需要将 Docker 软件回滚到 4.30.0 即可。（Mac 下验证有效，其他操作系统待进一步验证。） MySQL 开发中，最常用的应该就是数据库了。所以，先来搞 MySQL 数据库。
创建如下目录结构，并添加相关相关文件：
$ tree . ├── README.adoc ├── clean.sh ├── data │ └── mysql │ └── .gitkeep ├── docker │ ├── config │ │ └── mysql │ │ └── init.sql │ ├── env │ │ └── mysql.env │ └── images │ └── mysql.dockerfile └── docker-compose.yml
在 OpenJDK 21 升级指南 中，给大家分享了一下升级到 OpenJDK 21 中遇到的一些问题。文末留了一个小问题：生产环境的 Java 21 启动参数怎么配置？这篇文章将给出 D瓜哥的答案。
先说明一下生产环境的机器配置：4C8G，四个内核，8G 内存。
启动参数 鉴于 JVM GC 性能测试（二）：递增流量 和 JVM GC 性能测试（三）：真实流量 中，G1 GC 的惊艳表现，这里分别提供 Gen ZGC 和 G1 GC 两个配置。
两个配置差距级小，为了方便复制粘贴，还是分两个来展示。 Gen ZGC 配置 追求极致低延迟，就上 GenZGC，它通过牺牲大约 10% 的吞吐量，换来无与伦比的低延时。
注意：使用时，请修改日志目录！ ## 变量配置 ####################################################################### # java -XshowSettings:all --展示所有配置项（测试发现也不全） -Dfile.encoding=UTF-8 # https://zhuanlan.zhihu.com/p/455313866 # https://zhuanlan.zhihu.com/p/455746995 # https://blog.csdn.net/u014149685/article/details/83002405 # 随机数来源 -Djava.security.egd=file:/dev/./urandom -Djava.security=file:/dev/./urandom # https://docs.oracle.com/javase/8/docs/api/java/net/doc-files/net-properties.html # https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/net/doc-files/net-properties.html # DNS 过期时间 -Dnetworkaddress.cache.ttl=10 # -Dsun.net.client.defaultConnectTimeout=60000 -Dsun.net.client.defaultReadTimeout=60000 #-Dsun.net.inetaddr.ttl=300 # https://mdnice.com/writing/47e729bbf8e44431a396a481ed173dae -Djava.awt.headless=true # https://blog.csdn.net/maverick0/article/details/8282472 -Djmagick.systemclassloader=no # From Cassandra # On Java >= 9 Netty requires the io.netty.tryReflectionSetAccessible system property # to be set to true to enable creation of direct buffers using Unsafe. Without it, # this falls back to ByteBuffer.allocateDirect which has inferior performance and # risks exceeding MaxDirectMemory # https://blog.csdn.net/jdcdev_/article/details/132843927 -Dio.netty.tryReflectionSetAccessible=true # 内部中间件 # 注意：一些中间件会内嵌 Netty，这里建议同步修改其相关参数配置。 -Dump.profiler.shade.io.netty.tryReflectionSetAccessible=true -Dtitan.profiler.shade.io.netty.tryReflectionSetAccessible=true # Revert changes in defaults introduced in https://netty.io/news/2022/03/10/4-1-75-Final.html -Dio.netty.allocator.useCacheForAllThreads=true -Dio.netty.allocator.maxOrder=11 # 内部中间件 # 理由上面已讲 -Dump.profiler.shade.io.netty.allocator.useCacheForAllThreads=true -Dump.profiler.shade.io.netty.allocator.maxOrder=11 # Byte Buddy 支持21 -Dnet.bytebuddy.experimental=true -Dpfinder.shade.net.bytebuddy.experimental=true ## 参数配置 ##################################################################### # https://jacoline.dev/inspect -- JVM 参数诊断 # https://chriswhocodes.com/corretto_jdk21_options.html # https://docs.oracle.com/en/java/javase/21/docs/specs/man/java.html # https://blog.csdn.net/wxb880114/article/details/119888587 # https://www.cnblogs.com/three-fighter/p/14644152.html #- https://www.skjava.com/article/2134434173 # 解锁诊断参数 -XX:+UnlockDiagnosticVMOptions # 解锁试验参数 -XX:+UnlockExperimentalVMOptions # 启用 ZGC -XX:+UseZGC # 启用分代ZGC -XX:+ZGenerational # https://tech.meituan.com/2020/08/06/new-zgc-practice-in-meituan.html # 加快 GC 的时间和能力 -XX:ZAllocationSpikeTolerance=5 -XX:ConcGCThreads=2 -XX:ParallelGCThreads=4 # G1 GC #-XX:+UseG1GC #-XX:MaxGCPauseMillis=50 # 初始堆大小，等价于 -XX:InitialHeapSize -Xms4608m # 弱最大堆，尽量保持，但是可以突破 #-XX:SoftMaxHeapSize=3g # 最大堆大小，等价于 -XX:MaxHeapSize -Xmx4608m # 归还未使用的内存 #-XX:+ZUncommit # 设置每个线程的堆栈大小，等价于 -XX:ThreadStackSize=512k -Xss512k # https://cloud.tencent.com/developer/article/1408384 # 本地内存大小 -XX:MaxDirectMemorySize=512m # https://cloud.tencent.com/developer/article/2277327 # https://cloud.tencent.com/developer/article/2277328 # https://cloud.tencent.com/developer/article/2277329 # 元空间 # 设置为 256m 时，发生过一次频繁 GC 导致应用无法相应的问题 -XX:MetaspaceSize=512m # 最大元空间 -XX:MaxMetaspaceSize=512m # https://cloud.tencent.com/developer/article/1408773 # https://blog.csdn.net/lidf1992/article/details/75050219 # 编译代码缓存空间 -XX:ReservedCodeCacheSize=256m # https://cloud.tencent.com/developer/article/1408827 # https://malloc.se/blog/zgc-jdk15 # https://tinyzzh.github.io/java/jvm/2022/04/24/JVM_CompressedOops.html # https://www.cnblogs.com/star95/p/17512212.html -- 由于从 JDK15 开始， # -XX:+UseCompressedClassPointers 与 -XX:-UseCompressedOops 之间的强 # 关联被打破，文章里关于上述这种搭配是不正确的。 TODO 可以从新测试验证一线。 # TODO 如果开启 -XX:+UseCompressedClassPointers，不确定 32M 是否够用？ # https://www.zhihu.com/question/268392125 -XX:+UseCompressedClassPointers -XX:CompressedClassSpaceSize=48M # 关闭热度衰减 -XX:-UseCounterDecay # 内存占座 -XX:+AlwaysPreTouch # 禁止代码中显示调用GC -XX:+DisableExplicitGC # 关闭安全点间隔 -XX:GuaranteedSafepointInterval=0 # 避免循环无法进入安全点的问题 -XX:+UseCountedLoopSafepoints # https://blog.csdn.net/m0_46596655/article/details/123606813 -XX:LoopStripMiningIter=1000 # 打印命令行参数 -XX:+PrintCommandLineFlags # 显式地并发处理 GC 调用 -XX:+ExplicitGCInvokesConcurrent # https://panlw.github.io/15320998566522.html -XX:AutoBoxCacheMax=20000 # https://blog.csdn.net/zshake/article/details/88796414 # 省略异常栈信息从而快速抛出 -XX:-OmitStackTraceInFastThrow # https://www.jianshu.com/p/c9259953ca38 # 致命错误日志文件 -XX:ErrorFile=/path/to/log/jvm/hs_err_%p.log # https://blog.csdn.net/lusa1314/article/details/84134458 # https://juejin.cn/post/7127557371932442632 # 当JVM发生OOM时，自动生成DUMP文件。 -XX:+HeapDumpOnOutOfMemoryError # 设置上述DUMP文件路径 -XX:HeapDumpPath=/path/to/log/jvm/ # https://juejin.cn/post/6959405798556434440 # 设置 JFR 相关参数 # TODO 感觉这里不全乎，似乎需要 -XX:+FlightRecorder 来启用 # TODO 似乎可以设置文件，例如： -XX:StartFlightRecording=duration=200s,filename=flight.jfr # 不确定文件名是否可以这样配置，测试一下_%p-%t # Amazon Corretto JDK OK；Eclipse Temurin 不识别，并且监控报错 #-XX:StartFlightRecording=delay=5s,disk=true,dumponexit=true,duration=24h,maxage=5d,maxsize=2g,filename=/path/to/log/jvm/jfr_%p-%t.jfr.log #-XX:FlightRecorderOptions=maxchunksize=128m #-XX:StringDeduplicationAgeThreshold=threshold? TODO 测试之后才可以定 # https://zhuanlan.zhihu.com/p/111886882 # https://github.com/apache/cassandra/tree/trunk/conf # https://github.com/elastic/elasticsearch/blob/main/distribution/src/config/jvm.options # java -Xlog:help # 日志配置 -Xlog:gc*=debug,stringdedup*=debug,heap*=trace,age*=debug,promotion*=trace,jit*=info,safepoint*=debug:file=/path/to/log/jvm/gc_%p-%t.log:time,pid,tid,level,tags:filecount=10,filesize=500M # 分开设置可用，使用分开的配置 #-Xlog:gc*=debug,stringdedup*=debug,heap*=trace,age*=debug,promotion*=trace:file=/path/to/log/jvm/gc-%t.log:utctime,level,tags:filecount=10,filesize=200M #-Xlog:jit*=info:file=/path/to/log/jvm/jit_compile-%t.log:utctime,level,tags:filecount=10,filesize=50M #-Xlog:safepoint*=debug:file=/path/to/log/jvm/safepoint-%t.log:utctime,level,tags:filecount=10,filesize=50M # https://stackoverflow.com/a/44059335 # https://openjdk.org/jeps/261 # https://www.diguage.com/post/upgrade-to-openjdk21/ -- 内有详细介绍 # 开启模块权限：下面是D瓜哥需要的模块，请根据自己实际需求来调整。 --add-exports java.base/sun.security.action=ALL-UNNAMED --add-opens java.base/java.io=ALL-UNNAMED --add-opens java.base/java.lang.reflect=ALL-UNNAMED --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.math=ALL-UNNAMED --add-opens java.base/java.net=ALL-UNNAMED --add-opens java.base/java.security=ALL-UNNAMED --add-opens java.base/java.time=ALL-UNNAMED --add-opens java.base/java.util.concurrent.locks=ALL-UNNAMED --add-opens java.base/java.util.concurrent=ALL-UNNAMED --add-opens java.base/java.util=ALL-UNNAMED --add-opens java.base/jdk.internal.loader=ALL-UNNAMED # Netty 内部需要 https://stackoverflow.com/a/57892679 # https://github.com/netty/netty/issues/7769 # https://blog.csdn.net/thewindkee/article/details/123618476 --add-opens java.base/jdk.internal.misc=ALL-UNNAMED --add-opens java.base/sun.net.util=ALL-UNNAMED # 设置 -Dio.netty.tryReflectionSetAccessible=true 后，不设置该值也会报错 --add-opens java.base/java.nio=ALL-UNNAMED --add-opens java.base/sun.nio.ch=ALL-UNNAMED --add-opens java.base/sun.reflect.generics.reflectiveObjects=ALL-UNNAMED --add-opens java.base/sun.util.calendar=ALL-UNNAMED --add-opens java.management/com.sun.jmx.mbeanserver=ALL-UNNAMED --add-opens java.management/java.lang.management=ALL-UNNAMED --add-opens java.management/sun.management=ALL-UNNAMED --add-opens jdk.management/com.sun.management.internal=ALL-UNNAMED
在 OpenJDK 21 升级指南 中提到， OpenRewrite 可以帮忙解决一些升级 OpenJDK 中发现的问题。随着不断的探索，D瓜哥发现，OpenRewrite 的功能远远不止这些。下面就挑选一些重要的功能来给大家做一些讲解。
为了方便查看改动点，建议将代码交给版本管理工具，比如 Git，来管理。 快速入门 OpenRewrite 是一套对源码做重构的大型生态系统，可以帮助开发人员减少技术债。所以，它提供了一套的相关工具。对于大多数开发人员来说，最方便的也许就是基于 Maven 插件的相关工具。这里以对 Java 的 import 语句排序来为示例展示一下 OpenRewrite 的使用方法。
在项目的 pom.xml 中增加如下配置：
<!-- @author: D瓜哥 · https://www.diguage.com --> <plugin> <groupId>org.openrewrite.maven</groupId> <artifactId>rewrite-maven-plugin</artifactId> <version>5.30.0</version> <configuration> <activeRecipes> <!-- import 排序 --> <!-- https://docs.openrewrite.org/recipes/java/orderimports --> <recipe>org.openrewrite.java.OrderImports</recipe> </activeRecipes> </configuration> </plugin> 然后执行如下命令：
mvn rewrite:run 执行会输出一大堆东西，这里就不再展示，执行完成后，使用 Git 查看一下改动点。如下图：
图 1. 使用 OpenRewrite 排序 import 的改动点 将这些修改点提交，就完成了一次优化， OpenRewrite 的基本使用，你学废了吗？
这里再多说一句： 由于 OpenRewrite 精巧的设计，可以通过使用不同的处方，进行各种各样的优化。所以，最重要的一点就是了解 OpenRewrite 各种不同的处方及使用办法。下面就介绍一下常用的处方及使用办法。
常用处方 升级到 Java 21 在 OpenJDK 21 升级指南 中提到，可以使用“科技与狠活”来解决很多升级中遇到的问题。这里就来实操一把。
最近公司可以申请零净值 MacBook 笔记本，就随手申请了一个。由于有很多软件需要安装，就搜集了一下以前安装软件的命令，整理成一个安装脚本，分享出来，方便后续再次装机。
1. xcode-select 作为开发人员，这是基础工具包，必须安装：
xcode-select --install 2. 安装脚本 安装脚本主要构成如下：
2.1. oh my zsh 安装脚本先安装了 oh-my-zsh。最近帮同事搞 MacBook，没有 oh-my-zsh 的加持，写命令行浑身难受。
图 1. oh-my-zsh 由于安装 oh my zsh 会导致脚本退出，所以，单独安装：
#!/usr/bin/env bash # # Author: D瓜哥 · https://www.diguage.com # # 安装 oh-my-zsh sh -c "$(curl -fsSL https://cdn.jsdelivr.net/gh/ohmyzsh/ohmyzsh/tools/install.sh)" 2.2. Homebrew 脚本里面主要使用了 Homebrew 来安装软件。
图 2. Homebrew 2.3. sdkman Java JDK + Maven 等相关安装，主要使用了 Sdkman，方便多个版本相互切换。
图 3. sdkman 2.4. 感谢 jsDelivr 为了解决安装 oh-my-zsh 和 Homebrew 时，GitHub 访问不畅，使用 jsDelivr 将它们的安装链接进行改写，可以利用 CDN 加速，让安装过程更加顺利。
在做新需求开发或者相关系统的维护更新时，尤其是涉及到不同系统的接口调用时，在可维护性方面，总感觉有很多地方差强人意。一些零星思考，抛砖引玉，希望引发更多的思考和讨论。总结了大概有如下几条建议：
在接口注释中加入接口文档链接
将调用接口处写上被调用接口文档链接
将接口源代码发布到私服仓库
对于状态值常量，优先在接口参数类或者返回值类中定义
如果使用 Map 对象作为传输载体，要提供 Key 值定义常量
针对 Map 返回值，可以考虑使用将 Map 转化成对象
尽可能简化接口依赖
只传递必要字段，尽量避免大而全的接口
将接口的参数和返回值原始数据打印到日志中
将 RPC 接口的类名及方法打印到日志中
核心思想：以人为本，就近原则，触手可及
下面，D瓜哥对每一条建议做一个详细说明。
1. 在接口注释中加入接口文档链接 在做接口开发时，无论是对自有接口的升级改造，还是针对外部接口的从头接入，都涉及到接口文档。不同之处是，前者的工作重点是书写或者更新接口文档；而后者是根据接口文档开发合适的接入代码。但是，经常遇到的一个麻烦是，找不到接口文档。在组内需要找老同事询问；如果是跨部门，还需要两层甚至三层的进行转接，非常麻烦。
D瓜哥认为，在这种情况下，为了方便大家维护，最好的办法就是将接口文档链接直接放在代码注释中，这样后续维护的人员，直接就可以点击链接直达接口文档，简单方便高效。如果是新建的接口，就可以先创建一个空文档，把链接放在注释中，后续再书写文档内容。如果是维护已有接口，可以在维护时，将缺失的链接加入到注释中，自己方便，也方便其他人进行后续的维护更新。这样，在循序渐进的过程中，逐步就可以把文档链接补充到代码中，方便维护代码，也同步更新文档。
2. 将调用接口处写上被调用接口文档链接 在调用其他系统的接口时，没有接口文档，几乎寸步难行。在第一次接入接口时，绝大多数情况下，都是参考着接口文档做接入工作。但是，目前的情况时，接入时参考文档，参考完就随手把文档给“扔了”。后续如果还需要做进一步升级维护，还需要到处找接口文档；另外，交互的系统难免有一些 Bug，在和其他系统维护人员对接处理 Bug 时，只有接口没有文档，对方可能也需要去找文档链接。无形中，很多时间都浪费在了找文档的过程中。
D瓜哥最近尝试了一个实践，就是在接口调用的地方，把接口文档链接当做注释加入到代码中。这样，无论是后续维护升级，还是沟通协调处理问题，都非常方便。别人问接口是什么，连接口+文档都可以一把复制就搞定。
经过最近一段时间的实践情况来看，这个处理非常方便，是一个非常值得推广的实践。再插一句，也可以像一条建议一样，可以在维护代码时，不断把已接入的接口文档加入到调用接口的地方，循序渐进，方便后续人维护升级。
3. 将接口源代码发布到私服仓库 接口文档链接在注释中，在构建结果中就不复存在了。所以，为了方便接口使用方可以在接口中查询到对应的接口文档，就需要把源码也发布到私服仓库中。
这里只说明一下 Java 的相关处理办法。如果使用 Maven 作为构建工具的话，默认是不会将源代码发布到私服仓库中的。关于如何将源代码发布到，在 升级 Maven 插件：将源码发布到私服仓库 中已经做过相关介绍，这里就不再赘述。
除了将源码发布到私服仓库，另外，还建议编译构建时，保持方法的原始参数命名。这个也可以通过配置 Maven 插件来完成，具体配置见： 升级 Maven 插件：字节码文件包含原始参数名称。
4. 对于状态值常量，优先在接口参数类或者返回值类中定义 在做接口开发时，很多数据都有一个状态值，比如订单状态，再比如接口状态等等。目前的一个情况时，这些状态值大部分书写在文档中，在接入接口时，需要接入方自定义这些状态值。这就有些繁琐了，而且状态定义也不明确，甚至有可能遗漏一些重要的状态值。有些懒省事，直接在代码中硬编码一个魔法值，后续维护的跟还需要根据上下文反推这个值的含义，非常不利于维护。
D瓜哥个人觉得，有两个处理办法：
如果状态值不是很多，优先在接口参数类或者返回值类中定义。
如果状态值很多，可以考虑单独抽取成一个常量类或者枚举类。
这样使用的时候，触手可及。不需要到处去找。
5. 如果使用 Map 对象作为传输载体，要提供 Key 值定义常量 有些系统可能考虑方便增加字段，选择使用 Map 作为数据载体。自己开发的时候很爽，但是给接口接入却非常不友好。接入方从 Map 中获取数据时，要么自己定义 Key 值；要么直接使用魔法值硬编码在代码中。使用前者方案，就需要在各个接入方都需要自定义一套；使用后者，初期是省事了，后来维护的人员就懵逼了。这都无形中增加了很多维护成本。
在 制定组织内 Maven BOM 的一些规范 中，D瓜哥 介绍了一些组织内指定 Maven BOM 的一些规范。根据这些规范，D瓜哥 创建并维护了部门内部的 Maven BOM。今年，要求对部门内的陈旧依赖做一些升级工作。所以，在 关于升级 Spring 等依赖的一些经验 中介绍了一些升级开源依赖的经验；在上一篇文章 升级 Maven 插件 中介绍了升级 Maven 插件的一些注意事项。
D瓜哥一直坚持“机器可以干的事情，就应该交给机器干”。对于依赖管理，Maven Enforcer 插件就可以对依赖做必要的检查，所以，在 使用 Maven Enforcer 插件检查依赖 中，介绍了如何使用 Apache Maven Enforcer 来管理依赖。由于要维护部门内部的 Maven BOM，同时由于版本控的特质，所以，需要时长检查依赖升级情况。原来都是手动检查，需要一个一个去搜索各个依赖，不仅费时费力，而且还低效。最近，Maven 有一个插件可以胜任这个工作，它就是： Versions Maven Plugin。
依赖检查 Versions Maven Plugin 支持两种配置方式：
外置配置文件 maven-version-rules.xml；
内置在 POM 文件中，直接写在插件的 <configuration> 标签中。
第一种方案不方便迁移。还要额外管理一个配置文件。推荐使用第二种方式。另外，直接将这些配置放在 Maven BOM 中，使用继承的方式使用 Maven BOM，那么子项目就自动继承了这些配置。后续也只需要一个地方的配置即可。示例配置如下：
<!-- @author: D瓜哥 · https://www.diguage.com --> <plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>versions-maven-plugin</artifactId> <version>2.15.0</version> <configuration> <ruleSet> <ignoreVersions> <!-- 可以使用 ignoreVersion 配置忽略 SNAPSHOT、alpha、beta 版等 --> <ignoreVersion> <!-- 'exact' (默认) 或 'regex' --> <type>regex</type> <version>(.+-SNAPSHOT|.+-M\d)</version> </ignoreVersion> <ignoreVersion> <type>regex</type> <version>.+-(alpha|beta)</version> </ignoreVersion> </ignoreVersions> </ruleSet> </configuration> </plugin>
D瓜哥在 关于升级 Spring 等依赖的一些经验 中，介绍了一些升级 Spring 等依赖的一些经验。在 升级 iBATIS/MyBATIS 对处理 DuplicateKeyException 的影响 中，分析了升级 iBATIS/MyBATIS 对处理 DuplicateKeyException 异常的影响。在升级中，还遇到一些 Maven 插件相关的问题。这里也分享出来，希望对大家有所帮助。
Properties 文件编码错误 在升级过程中，遇到过 Properties 文件编码错误的问题。可以通过配置对应的编码来解决这个问题。配置如下：
<!-- D瓜哥 · https://www.diguage.com --> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-resources-plugin</artifactId> <version>3.3.0</version> <configuration> <propertiesEncoding>ISO-8859-1</propertiesEncoding> </configuration> </plugin> 参考资料 Apache Maven Resources Plugin – Filtering Properties Files。
使用 Maven Enforcer 插件检查依赖 私以为“机器可以干的事情，就应该交给机器干”。对于依赖管理，Maven Enforcer 插件就可以对依赖做必要的检查。所以，推荐使用 Maven Enforcer 插件来检查低版本及有安全漏洞的依赖。
详细介绍请参考： 使用 Maven Enforcer 插件检查依赖
字节码文件包含原始参数名称 一些对外发布的依赖，建议将原始参数名称编译到构建结果里。可以通过指定构建参数来完成。
<!-- D瓜哥 · https://www.diguage.com --> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>3.11.0</version> <configuration> <!-- https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javac.html --> <compilerArgs> <arg>-parameters</arg> </compilerArgs> <parameters>true</parameters> </configuration> </plugin> 参考资料 Apache Maven Compiler Plugin – Pass Compiler Arguments
解决测试依赖问题 部分项目可能已经使用了 JUnit 5，但是执行测试代码时，可能报错。可以使用如下配置来解决这个问题：
