经过几年的酝酿（或许还有桶装陈酿过程？），我们终于发布了AsciidoctorJ 1.6.0版本！这些构件可以从https://bintray.com/asciidoctor/maven/asciidoctorj/1.6.0[Bintray^] 和 Maven Central 获取。
在您升级之前，有一些重要的事情您需要了解，这篇文章将会涵盖这些内容。尽管AsciidoctorJ仍然是基于强大的https://asciidoctor.org[Asciidoctor^] RubyGem构建的，但它已经成长为一个具有自身地位的项目。这个版本为新老用户带来了稳定性和关键性的增强。拿起一杯，让我们为您倾注所有的细节。
一个实现SemVer的重要跳板
尽管版本号表明，但这个版本应该被视作一次主要更新。因此，它与1.5.x系列版本在二进制层面上不兼容。
AsciidoctorJ 1.6.0 是一个最终的转型版本，为的是准备切换到语义化版本控制（SemVer）。这一次我们打破了规则，但出于一个好的理由。考虑到1.6.0分支已经搁置了很久，我们希望能够开启它，以便收集反馈并找出一些在跳跃到2.0.0版本及SemVer之前没预料到的问题。如果一切顺利，我们预计在这个版本发布不久后会跟随2.0.0版本的发布。到那时，我们将开始根据SemVer规则对AsciidoctorJ进行版本控制。
要了解更多关于SemVer以及它如何影响一般的Asciidoctor项目，请参阅[切换到语义化版本控制]。(https://asciidoctor.org/news/2018/12/31/making-the-switch-to-semver/)。
转向使用SemVer也意味着AsciidoctorJ将独立于Asciidoctor进行版本控制。AsciidoctorJ已经演变成了远不止一个打包到JVM上的Asciidoctor RubyGem那么简单。它拥有一个完整的API，包括基于Java的扩展和与Java生态系统的紧密集成（例如，JUL、Ruby对象桥接等）。独立的版本线将使其能够更快地进化，并帮助每个人更好地了解每个版本中可以期待什么。最重要的是，它将解决那个导致1.6.0版本多年积压的具体情况。
新功能
- 主要API和包装变更
-
自从AsciidoctorJ项目开始以来，我们对JRuby以及它如何连接Ruby和Java对象有了很多了解。利用这些知识，我们已经完全重新设计了底层集成，以解决原始设计中的不足之处。
这次重新设计要求我们对API进行了重大更改，这对于AsciidoctorJ的持续发展是绝对必要的。但这也为我们提供了修复许多在1.5.x版本中无法在不破坏兼容性的情况下修复的错误的机会。你会高兴地知道，重新设计消除了在使用1.5.x版本编写扩展或浏览文档模型时可能遇到的问题。
作为这一变更的一部分，为了适当地隔离它们，我们将API和实现类分割到了不同的包和JAR文件中。我们还通过映射Asciidoctor中的所有节点类型并移除了ContentPart和StructuredDocument API来调和相争的文档模型。请参考API文档（https://www.javadoc.io/doc/org.asciidoctor/asciidoctorj-api/1.6.0[api^], impl）了解哪些类型可用以及它们是如何组织的。
- 重构了扩展API
-
感谢重新设计，基于JRuby的实现在API后面隐藏得更好了。特别是，在API中再也没有对JRuby的RubyObject类的引用了。
抽象语法树（AST）的接口被完全重命名，以更好地代表它们的用途。例如，AbstractNode接口被重命名为ContentNode，AbstractBlock被重命名为StructuralNode，Inline被重命名为PhraseNode。甚至更多的AST在Java中得到了映射，包括列表和定义列表，以及在扩展处理器中创建表格结构的助手。
总的来说，用于扩展和AST的API应该感觉像一个纯Java库（例如，
getAttr()`现在变成了`getAttribute()）。你甚至可以使用基于注释的配置来定义扩展处理器（例如，@Name）。查看https://github.com/asciidoctor/asciidoctorj/blob/master/docs/integrator-guide.adoc[集成者指南^]以了解全部相关信息并找到许多示例。
- 新增转换器API
-
引入了一个新的转换器 API，使得完全使用 Java 实现一个自定义输出格式的转换器成为可能。这个 API 允许你扩展 Asciidoctor 从 Java，类似于你可以使用扩展 API 已经做的那样。你可以通过跟随https://github.com/asciidoctor/asciidoctorj/blob/master/docs/integrator-guide.adoc#publish-everywhere-adapt-asciidoctor-to-your-own-target-format[转换器文档^]来学习如何使用这个新 API。
实际上，已经有一个转换器通过Groovy使用这个API convert AsciiDoc to Leanpub-flavored Markdown。
- 访问Asciidoctor的日志
-
Asciidoctor会在遇到文档问题时通过Ruby日志记录器记录错误和警告消息。将Asciidoctor集成到您自己的软件时，捕获这些日志消息以便适当处理非常重要。以前，这些消息对AsciidoctorJ来说是无法获取的。但现在不再是问题。新的https://github.com/asciidoctor/asciidoctorj/blob/master/docs/integrator-guide.adoc#logs-handling-api[日志处理API^]能够捕获Asciidoctor中记录的消息，并将它们路由到您自己的日志处理程序。
- 更好的文档
-
AsciidoctorJ 1.6.0 提供了经过扩展和测试的 documentation 用于编写扩展和转换器。这份文档保证是正确的，因为它在每次提交时都会经过测试 ;) 而且正在将这份文档整合到基于Antora的新Asciidoctor文档站点中的过程中。
请参考 发布说明 以获取此版本更改的更详细报告。请记住，由于1.6.0的开发与1.5.x的开发长时间平行进行，许多从1.6.0中的变化您可能已经熟悉了，因为它们被回溯合并到了1.5.x的发布线中。
迁移说明
如果您只使用 Asciidoctor、Asciidoctor.Factory 和 *Builder 类（例如，Asciidoctor#convertFile），您可能不需要更改您的代码。实际上，https://github.com/asciidoctor/asciidoctor-maven-plugin[Asciidoctor Maven 插件^] 和 Asciidoctor Gradle 插件已经可以与这个版本协同工作，主要是因为它们只依赖于公共的 load/convert API。
对AST和扩展API所需的变更引入了破坏性改变，这需要修改您现有的扩展。迁移一个扩展就是要符合新的API。这主要涉及切换到AST接口的新名称以及与更新后的方法签名保持一致。除了名称和签名的变化外，API仍应该是可识别的，因此与您现有的逻辑兼容。
这里有一些为AsciidoctorJ 1.5.8和1.6.0编写的扩展示例，可以让你了解需要注意的类型变化：
如果您在迁移扩展或文档自省代码时遇到困难，请在https://github.com/asciidoctor/asciidoctorj/issues[问题跟踪器^]中提出问题，这样我们就可以找到一条前进的道路。
Java 兼容性
Asciidoctor 1.6.0至少需要Java 8环境。它也可以在Java 11上运行，并且已经过Java 11的测试。
从AsciidoctorJ 1.6.0版本开始，该项目将其Java兼容性与[官方Oracle Java SE支持路线图](官网链接进行对齐。虽然AsciidoctorJ不要求使用Oracle Java SE，但该路线图可作为判断哪些Java版本是当前最新的有用标志。
Asciidoctor 1.6.0还不支持在模块路径上运行，这是Java 9引入的http://openjdk.java.net/projects/jigsaw/[Java平台模块系统^]的一个关键功能。我们希望在未来的版本中能够实现这一点。然而，这将取决于AsciidoctorJ依赖项朝这个目标取得的进展，尤其是JRuby。尽管有这个限制，你仍然可以在Java 11上运行Asciidoctor 1.6.0。
致谢
我们想借此机会点名几位关键人物，是他们汇聚一堂，让这次发布活动成为了今天的模样。
-
感谢[Jérémie Bresson^]启动了API和实现包之间的拆分，并使API签名现代化的工作。
-
谢谢 Abel Romero 在JUL日志集成设计及首先在Maven插件中测试方面的帮助。
-
感谢Frank Becker对Gradle构建过程进行了彻底的整修和流程优化。
-
感谢[Guillaume Grossetie^]在API和实现的各个方面进行了大量的整理和改进，并通过启动[AsciidoctorG]来对重设计进行压力测试。
-
感谢 Charles Nutter、Thomas Enebo 和 JRuby 团队创建并维护 JRuby，AsciidoctorJ 就是基于它。
-
最后，我们的“前辈”Alex Soto，感谢他发起了AsciidoctorJ项目，并且向我们展示了可能的愿景。
当然，还有很多其他人需要感谢。正如我们多次说过的，如果没有 [许多志愿者](https://github.com/asciidoctor/asciidoctorj/graphs/contributors) 令人难以置信的工作和合作，这个项目是不可能实现的。所以，谢谢你！
2.0.0版本的展望
破坏性变更还没有结束。朝着2.0.0发展，我们希望进一步分离AsciidoctorJ的API和它的实现。我们的重大目标是支持在相同的公共API下，使用像Asciidoctor.js这样的替代实现。
为了帮助我们达到2.0.0版本，我们请求您测试1.6.0版本，并让我们知道如果您遇到任何问题或变动，阻止您迁移到它。现在正是在2.0.0版本发布前确保一切正确的机会。请在[issue tracker^] https://github.com/asciidoctor/asciidoctorj/issues 中提交您发现的任何问题。
感谢您与我们一同踏上这段旅程，我们致力于将AsciiDoc的最佳体验带到JVM上。