API 重构：过去、现在和未来

发布于 作者

早在 11 月，我们宣布了 第一个 API 重构计划。在那篇文章中，我们简要地说明了我们的总体目标。

jQuery UI 正在进行 API 重构，旨在简化 API 的大小，以提供更稳定的代码库，使其更易于学习和使用。我们将在接下来的几周内发布拟议的更改，以便收集来自社区的反馈。我们的目标是在 1.9 中同时支持旧（当前）和新（提议）API，然后在 2.0 中删除对旧 API 的支持。

现在已经是三个月后了，有两点很清楚：1) 发布所有拟议的更改需要不止几周的时间；2) 我们没有提供有关计划更改及其背后的原因的足够信息。

过去

当 jQuery UI 首次创建时，它是新插件和现有插件的组合。引入现有的流行插件对所有人都有利：jQuery UI 发布得更早，插件更多，原始作者的辛勤工作得到了 jQuery 项目的公开认可和支持，而现有用户群则获得了对其正在使用的代码的官方支持。不幸的是，这种方法也有缺点。由于现有插件是由不同的作者使用不同的设计原则和不同的编码风格编写的，因此 jQuery UI 内部缺乏一致性。在 1.0 和 1.8 版本之间，曾尝试对 API 的各个部分进行标准化，但从未进行过足以进行必要更改的协调努力。

除了插件之间的不一致外，在过去三年半的时间里还出现了其他问题。随着用户请求越来越多的功能，选项、方法和事件的数量不断增加。随着时间的推移，这导致了我们今天所处的状况，即像可拖动元素这样简单的东西有近 30 个选项。一方面，如此多的各种用例可以得到处理，通常只需要使用其中的一两个选项，这令人印象深刻。另一方面，对于新用户而言，寻找要使用的合适的一两个选项可能是一项艰巨的任务。

现在

认识到现有问题，我们对 1.8 版本采取了不同的方法。我们定义了一个构建插件的新流程，该流程侧重于简化的 API，这些 API 易于扩展。随着 1.8 版本的成功，尤其是自动完成小部件的简洁性和灵活性，我们确信我们的新流程正在发挥作用。拥有新的流程和新的标准，我们决定回过头来使用相同的设计流程重新设计所有现有插件。10 月，jQuery UI 团队在波士顿聚在一起，对所有现有插件进行第一次重构。几周后，我们开始发布拟议的更改以收集社区的反馈。我们仍在为特定插件完成一些细节。

我们的目标是在 2.0 版本中拥有一个完全焕然一新的项目。我们将拥有一个更简单的 API、更好的稳定性、完整的文档和每个插件的完整测试套件。但是，要实现这一目标需要许多向后不兼容的更改。我们意识到这可能很痛苦，并且正在尽一切努力减少升级的痛苦。具体而言，我们在实施新 API 时正在执行以下操作

  • 确保我们拥有 2.0 API 的完整测试套件
  • 为 1.8 API 创建一个单独的测试套件
  • 在新的功能之上重新实现任何已弃用的功能
  • 在旧 API 和新 API 无法并存的情况下默认为 1.8 API

这种方法有几个好处，其中最重要的一个好处是升级到 1.9 应该不会破坏任何现有的页面。事实上，1.9 版本对 1.8 API 的支持将比任何 1.8.x 版本都要好。随着插件为 1.9 重构，1.8.x 中存在的许多错误将得到修复，而一些修复将无法轻松移植到 1.8 分支。由于 1.9 版本中对 1.8 API 的支持实际上是在 2.0 API 之上构建的新代码，因此它受益于这些错误修复。为 1.8 API 添加完整的测试套件确保这两个 API 中的这些错误确实得到了修复。

默认为 100% 支持 1.8 API 对于升级到 1.9 非常有用，但它不提供确定您是否已准备好升级到仅使用 2.0 API 的方法。为了解决这个问题，我们添加了一个新的标志，jQuery.uiBackCompat。如果您加载 jQuery，然后设置 jQuery.uiBackCompat = false，然后加载 jQuery UI，则不会加载任何 1.8 API。这将导致只有 2.0 API 可用，并允许您测试您的页面与新 API 的兼容性，并让您确信您将在 2.0 发布时准备好升级到 2.0。

未来

当 jQuery UI 2.0 发布时，我们将不再支持 1.8 API。但是，1.9 中的 1.8 API 兼容层应该继续工作；它只是不会包含在 2.0 版本中，并且不再得到官方支持。所有新的插件都将经过新的设计流程，因此像这样的重大 API 更改应该不会再次发生。一旦现有的插件更新到我们的新标准，我们应该能够比以前更快地推进项目。

值得一提的是，只有小部件、实用程序和效果在 1.9 中进行重构。所有交互都将为 2.0 重新编写，因此它们将经历不同的实现流程。作为 jQuery UI 的用户，除了发布日期之外，您不应该在小部件重构和交互重写之间感受到太多区别。

我们知道没有人期待重构现有的代码以与 API 更改一起使用，并且我们正在努力确保过渡过程清晰明了。我们希望您，我们的用户，能够理解我们必须利用这次机会改进 jQuery UI，使其在长期内更加健壮、可扩展和易于维护。

关于“API 重构：过去、现在和未来”的 29 个想法

  1. Steve Ottenad 于 说：

    这听起来像是一个很棒的计划，可以推动 JQUI 向前发展，同时仍然适应旧版本。在 1.9/2.0 中绝对应该有一些日志/错误消息，写出哪些特定实现已弃用。

  2. Chris Tierney 于 说：

    我认为这个计划很好。1.9 允许我开始进行针对 2.0 版本的更改，这将为 jQuery UI 提供一个稳固的未来。我希望看到 JUI 的未来取得巨大进步。感谢大家付出的辛勤努力。

  3. Phil 于 说：

    我同意这是长期最合理和最可持续的方法，但我还要补充一点，对于重大更改，或者关于为过渡到 2.0 API 做准备需要查找的内容的建议，提供一些好的具体示例将非常棒。

  4. Scott González 于 说：

    Phil：重大更改的列表以及升级路径将在 1.9 和 2.0 版本中得到完全记录。在此之前，您可以使用各个 API 重构文章查看将要进行的更改。

  5. Scott González 于 说：

    Steve：我认为为已弃用的功能添加警告需要相当多的额外代码。如果社区中有人有兴趣构建另一个层来添加警告，那就应该可以做到。

  6. David 于 说：

    听起来都不错。现在头疼总比以后出现更大的问题要好。期待 1.9 和 2.0 版本，感谢 JUI 团队的出色工作！

  8. Steve 'Cutter' Blades 在 说:

    听起来很棒。一致性在整个过程中都非常重要。是否有发布路线图？我知道包含网格在您的清单中，并得到一些主要参与者的支持，我想知道还有哪些新的小部件即将推出。我知道您不想让库过于臃肿（重构将有助于解决这个问题），但似乎还有一些关键部分需要真正完善（例如网格和树）。

  11. Michael 在 说:

    听起来都很棒，但我宁愿看到你们现在把时间花在添加新的 UI 控件上，而不是重构现有的控件（这些控件似乎对人们来说运行良好）。新的控件可以使用您描述的新技术制作，然后当您涵盖了最常用的 UI 控件类型后，您可以回头让一些最初的控件更符合新的控件。并不是说我一定要改变你的想法，但我怀疑我不是唯一有这种想法的人。似乎你们正在开发的新控件已经开发了很长时间了。无论如何，你们都做得很好，我期待着接下来会发生什么。

  12. Scott González 在 说:

    Michael: 我们目前无法为我们大多数现有的插件提供支持。目前有将近 800 个未解决的工单。由于有如此多的未解决工单，再加上我们对维护现有的代码库没有信心，这意味着现有的插件实际上对人们来说并不正常工作。添加更多插件会使情况更糟，因为它会增加所需的维护量，而不是减少维护量。现在解决问题是唯一可行的解决方案。

  13. Ross 在 说:

    我理解想要保留一段时间向后兼容性，并简化升级过程，但请不要为了让 1.8 用户满意而牺牲 2.0 的功能。我宁愿拥有一个功能减少 50% 但改进 200% 的库，而不是被兼容性考虑所束缚。

    ~Ross

  14. Gordon 在 说:

    CSS API 怎么样（为了方便起见，我们这么称呼它）？

    使用 jQuery 1.x 和主题的当前情况是，要么所有内容都应用了主题，要么没有任何内容应用主题，您必须自己设置所有样式。要解决这个问题，您需要编写比 themeroller CSS 更具体的 CSS 来重置和重新设置您想要使用的样式，而不是 themeroller 主题。这真的很繁琐且容易出错。某种机制，让您可以选择性地设置主题并自己设置未设置主题的内容，将非常有用。

    我们最常遇到的情况是，当您想要在使用手风琴或选项卡的页面上使用日期选择器或对话框时。您希望日期选择器和对话框使用 theme roller，但手风琴和选项卡使用页面样式。

  16. Scott González 在 说:

    Gordon: 我们所有插件只需要加载功能性 CSS，例如 jquery.ui.dialog.css。然后您可以根据需要设置插件的样式。此外，ThemeRoller 已经支持根据选择器设置主题范围（请参阅下载时的高级选项），因此您可以设置要适当地设置样式的小部件的范围。

    但是，我们确实计划更新 CSS 框架、ThemeRoller 以及我们小部件中的样式功能。我们正在努力将所有与样式相关的类（例如 ui-corner-all）与我们的部件分开，并添加选项以根据功能性类将要应用于部件的类。有关更多详细信息，请参阅 http://bugs.jqueryui.com/ticket/7053。

  17. Ross 在 说:

    Scott: 没有，我没有具体的问题。我只是在许多项目中经历了，这些项目因对向后兼容性的关注而受到致命限制。我理解这种需求，但这不是大多数技术革命性进步背后的思维方式。一个很好的例子是 HTML5，它完全没有采取措施确保与 IE 的兼容性。如果它这样做了，它的成功和进步将受到极大限制。

    我不完全确定您要更改什么，或者要更改多少。我只是想建议我（可能还有其他人…？）更希望拥有新功能（或者至少拥有新功能和未来扩展的可能性），而不是庞大的向后兼容性。

  18. Scott González 在 说:

    Ross: 您的总体关注点当然有效，但很高兴知道您没有具体的问题。您会很高兴知道，当我们重新设计现有插件的 API 时，我们完全忽略了如何保持向后兼容性。现有 API 对新 API 的唯一真正影响是它们是一组我们知道需要支持的用例。在设计过程中，我们会查看现有的 API 并询问“在新的设计中，现有的选项/方法/事件的功能应该如何实现？” 在设计过程中，我们实际上从未考虑过向后兼容层面的技术实现。这就是为什么有可能出现 1.8 API 和 2.0 API 彼此冲突的区域。在这些情况下，我们将通过让向后兼容层覆盖新功能来默认使用 1.8 API。但这不会影响 2.0 API 或如果您在 1.9 中将 $.uiBackCompat 设置为 false 时可用的内容。

    总之，我们完全同意您的观点。过去犯的错误不应该阻碍未来进步。1.8 API 和 2.0 API 之间的变化量实际上相当大，但我们确保为每项更改提供升级路径。

  20. Glen Somerville 在 说:

    关于 Datepicker 还有一点需要说明。如果在 onClose 和 onSelect 等事件中传递的日期是 JavaScript Date 实例而不是字符串，那就太好了。我知道可以通过这些事件中的 ‘inst’ 数据轻松地构造 Date 实例，但是我不明白为什么 selectedDay 是一个字符串，而 selectedMonth 和 selectedDay 应该是整数。

  21. Glen Somerville 在 说：

    看起来我之前的帖子没有显示出来……这是我对 jQUI 2.0 的一个请求。

    如果小部件的事件可以在小部件（例如 Datepicker）所附加的元素上触发，而不是必须在选项中以函数的形式发送，那就太好了。这将为在单独的逻辑结构中附加事件提供一种更简洁的方式，使 MVC 类型模式（如 Backbone.js 等）的使用更简单、更清晰。jQuery Tools 具有此功能，这很不错。

    jQUI 的功能集与竞争对手相比仍然是最大的之一。所以继续努力吧！谢谢！

  22. Scott González 在 说：

    Glen：你要求的功能已经存在了（而且存在了很长时间）。也许你特别指的是 datepicker，它是 jQuery UI 中唯一没有使用小部件工厂的，因此不符合我们的标准。

  25. Gordon 在 说：

    @scott 很好，知道 themeroller 中有这个功能，我之前并不知道。

    也许你应该让 themeroller 界面中这部分更显眼一些？

  26. jonas 在 说：

    这些人谈论了很多，JUI 是我见过的最好的东西，很好，很完美。如果它会发生变化并失去兼容性，那很好，整个社区都必须接受它并做出贡献以使其变得更好。

    JUI 团队，祝贺你们完成如此伟大的工作。希望我很快就能下载它。

  29. Roch 在 说：

    关于从标签中删除对 cookie 的内置支持。

    我不是程序员（这也是 jquery 如此吸引我的原因之一），所以可能是我遗漏了什么，但是关于删除内置 cookie 支持的解释，“跨页面状态管理应该容易，但不应该内置”，这是不够的。为什么“应该”不内置？目前，使用 cookie 来记住标签状态非常容易。从这个用户的角度来看，改变这一点是朝着错误的方向迈进了一步。我的观点是，标签的内置 cookie 支持“应该”内置。为什么我的“应该”不如解释这种变化的“应该”重要？

    我想知道，除了作为解释提供的“应该”之外，维护标签的内置 cookie 支持的缺点是什么。优点是易用性。缺点是什么？