开发 Web 服务可能会遇到哪些陷阱/提示

Posted 2023-02-24

【中文标题】开发 Web 服务可能会遇到哪些陷阱/提示

【英文标题】：What are some of the pitfalls/tips one could give for developing a web service

【发布时间】：2011-04-19 21:08:21

【问题描述】：

希望在 php 中开发 Web 服务 (api)，以便为客户提供与我们平台集成的更简单方法。有些工作流程调用将通过用户/通行证以及一些报告选项进行验证。

抱歉，我无法发布有关该主题的更多详细信息或代码，而且我从未开发过 Web 服务，但有通过 SOAP 使用它们的经验。

现在我还需要提供工作流的状态或状态，我认为 REST 将是这里的最佳选择，但仍在寻找关于此的意见。

对于报告，我想提供不同的选项，例如 XML、Excel/CSV，有什么理由我会选择其中一个吗？

我应该注意哪些陷阱？

任何人都可以提供哪些宝石。

提前感谢任何帮助，因为这对我来说非常重要。

更新 #1：

最安全的方法是什么？ 什么是最灵活的方法 （独立于平台）

更新#2： 关于数据流的一点点。 每个用户都有使用 API 的凭据，并且用户之间不会共享任何数据。用法是提交请求，处理请求并返回。没有更新。 （想想谷歌）发出搜索请求并给出结果，但在我的情况下，只给出一个结果。 不知道这是否需要，所以仅供参考。

【问题讨论】：

一个简单的建议：如果您希望您的 web 服务能够长期存在并且可以增长，那么从一开始就要求接口的版本号。

类似 api.host.com/v1/ 的东西？我想我已经看到了，很好的提示

您可以将版本存储在 URL 中，也可以嵌入在请求中（例如在有效负载内部或作为标头）。另外，我真的很喜欢使用JSON-RPC，因为它在大多数语言中都非常容易解析，并且非常灵活，因为您可以在 JSON 表示法中嵌入几乎任何东西。 REST 并不是真正的协议，而是一种风格。因此 JSON-RPC 请求将是 REST 调用的一种形式... SOAP 和 XMLRPC 也是不错的选择，具体取决于您的需求...

@ircmaxell 漂亮的二维码，有趣的消息=P

【参考方案1】：

Always handle errors and exceptions.

问题总是会在应用程序/api 中体现出来。无论是在开始还是通过进一步的发展。不要将此作为结束任务，并在发生错误时明确说明，并提供有据可查的响应消息。

此外，如果您的服务将处理许多请求，并且对于相同的资源 id（独立于用户）返回相同的资源，请务必缓存信息。这不仅是出于性能原因，也是出于错误出现的情况。通过这种方式，您至少可以为客户提供一些服务（可能有用，需要明确的更多上下文）。

【讨论】：

另一个好技巧，谢谢。我将无法使用缓存，因为每个请求都是独一无二的，但我确实理解这个想法背后的概念。

【参考方案2】：

我能提供的最大和最重要的一项是保证您在 WS 背后的基础架构，或者至少您通过 WS 提供的服务是无状态的。一旦你偏离了这一点，它就会变成一场噩梦，你将开始不得不硬塞代码以保护你的数据不被弄乱。

一个例子是两个客户端通过 WS 对数据进行更改，即...保存配置。你如何在后端处理它会让事情变得有趣。如果您的数据只是出站，那么如果您必须支持将数据推送到后端，那么您的情况要好得多。

此外，还要像对待任何面向公众的 API 一样深入思考 API。当您在野外发布一个版本，然后决定更改或弃用 API 需求时，就会开始给使用您的 WS 的客户群带来问题。

【参考方案3】：

我目前正在开发一个包含 Web 服务（或 ASP.NET MVC 中的 2 个）的 Web 应用程序，我强烈建议查看面向服务架构 (SOA) 背后的原则，因为我发现最重要的是一方面是正确设计 Web 服务 API，因为这会影响后端的其余部分，要么让你的生活更轻松，要么让你因为沮丧而陷入困境。

从本质上讲，SOA 意味着围绕业务流程设计 Web 服务，即使用您的 API 的人可能如何使用它。

一个好的设计总是一个好主意，所以我强烈建议你在开始编码之前先阅读 Web 服务设计原则，然后再为自己或其他不幸的人免去很多悲伤。

还要确保您的设计是敏捷的，因为它会随着您的公司和客户之间的沟通而频繁变化。

【讨论】：

很好的提示，您可以提供任何好的链接吗？我也会谷歌这个话题

【参考方案4】：

与实现相关的内容多于设计： 我会决定服务的输出是 XML - 这可以很容易地被所有体面的语言解析。此外，如果某些客户端需要其他输出，您可以通过一些 XSLT 处理器转换这些 XML，并提供“其他”Web 服务、输出 JSON 或其他任何他们需要的内容。 关于报告，这取决于报告的使用方式——如果客户处理它们并且他们只需要报告中的数据——那么再次建议使用 XML。在我看来，使用 CSV 更难，因为您必须考虑所有类型的特殊情况，例如“如果我的数据包含分隔符字段会发生什么”、“客户端是否能够指定分隔符”、“我将如何表示嵌套数据”，或者所有这些都直接使用 XML。 如果您的客户需要开箱即用的报告，您可以使用 BIRT - 美丽且免费

【讨论】：

是的，我更倾向于 xml，但也想提供 JSON 作为替代方案。如果我同时提供两者，我认为编写代码不会太多。最终用户可以为 JSON 或其他东西传递一个可选标志

【参考方案5】：

提供 JSON、CSV、YAML 或 XML 等多种输出效果很好 - 以极低的成本让最终用户感到舒适！转储数据总是比处理更容易，并且说它们出于某种原因已经解析了 JSON - 将它连接到您的 API 比实现（比如 XML 解析器）容易得多。现在我到处都能看到 XML 解析器，所以这应该不是问题，但我更喜欢 JSON 的“空气”性质；我对 YAML 进行了一些研究，但从未使用过它——但它看起来很有希望，我会明确地将它用于我的下一个项目的配置文件。

在任何动态处理用户提供的任何输入的安全方面，人们应该将此类输入视为即使用棍子也不会戳的东西。

恕我直言，无状态 REST 比 SOAP 更好，因为它的开销更少，人们可以从终端使用 curl 或 wget 轻松地手动与 REST-api 通信。可以这么说，快速启动。

我建议你深呼吸，用铅笔和纸，坐下来画出所有需要的东西。然后你删除不那么重要的东西，拿一张新纸开始整理。您可以在 API 的下一版本中添加不太重要的内容。

尽量设计 API，这样您就不会把自己锁在一个角落里，不要假设它接下来会走向何方。

【讨论】：

我在考虑 XML 和 JSON，但以低廉的成本提供更多是另一个不错的选择，谢谢