Java Spring RESTful 最佳实践 - 需要示例/教程

Spring RESTful best practice - example/tutorial needed

提问by Turar

SHORT STORY: I'm looking for tutorial or a github project that has an example of RESTful service design "best practices".

简短故事：我正在寻找教程或 github 项目，其中包含 RESTful 服务设计“最佳实践”的示例。

LONG STORY: I'm going through the "official" Spring tutorial for designing and implementing web services: http://spring.io/guides/tutorials/rest

长篇故事：我正在阅读用于设计和实现 Web 服务的“官方”Spring 教程：http: //spring.io/guides/tutorials/rest

It has an example of a small project. They are using "hexagonal architecture" and a bunch of "event" classes for this project. Going through it, I can't help but note that it seems way too over-engineered, for an example project. There are over 50 classes, not counting the tests. Is this really the "best practice" example of such a service? If not, are there any other examples that are better?

它有一个小项目的例子。他们正在为这个项目使用“六边形架构”和一堆“事件”类。通过它，我不禁注意到，对于一个示例项目，它似乎过度设计了。有超过50个班级，不包括考试。这真的是此类服务的“最佳实践”示例吗？如果没有，还有其他更好的例子吗？

采纳答案by yotsov

I cannot point you to a tutorial, but can mention some things based on experience with writing RESTful services using Spring MVC.

我无法为您提供教程，但可以根据使用 Spring MVC 编写 RESTful 服务的经验提及一些事情。

1. split the Controllers from the business logic. Concerns to have in the Controllers: most of all error handling, also potentially authorization. The Controller methods might be quite thin initially, and just dispatch to corresponding business logic methods. That's not a bad thing, soon your Controllers will grow with issues of interfacing clients.

2. speaking of error handling, it is quite hard to get it right in a RESTful service. You definitely need to have a way to nicely inform the clients of errors, via structured data. That should be a part of all your responses, I guess. You will need to decide which errors you send back info about, which ones you are silent about and just log, etc.

3. most probably you will have some data objects for the requests you are getting, and the responses you are sending. Package them in a separate jar. Add to this jar interfaces, implemented by your Controllers. Add also a simple second implementation of these interfaces, that makes calls to your service. Here you go, you have a client lib. Distribute it, make your Java clients happy.

4. Even though now you have a nice Java client lib, do not forget to also test your service with curl, and document how to use it this way, with simple calls. Make your non-Java users happy.

5. There are all kinds of libs for "unit" testing Controllers, by mocking up more or less of the internals of a web server. These are very useful, but do not limit yourself to them. Have a qa env, where you fully deploy your service, and have a qa app which sends real fully fledged requests to the instance of your service on the qa env, and analyses their responses.

6. Try to keep things simple and consistent across the different calls. For example every response can contain the same "error" part with the same fields giving information in a structured programatically usable form about what went wrong.

7. REST is a nice abstraction, but has its limitation: in practice, /delete.json?id=3 can have very different effects on different services. Do not expect your clients to be able to guess what "add" and "delete" will mean in your particular case, as they will probably guess differently from what you expected. Instead, provide in your documentation some information about what your service will be doing under the hood. We are not yet at a stage where we are able to have components communicating via the knowledge of just a very thin interface, staying agnostic of their internals, unfortunately.

1. 将控制器与业务逻辑分开。控制器中的问题：最重要的是错误处理，还有潜在的授权。Controller 方法一开始可能很瘦，只是分派到相应的业务逻辑方法。这不是一件坏事，很快你的控制器就会随着与客户端的交互问题而增长。

2. 说到错误处理，在 RESTful 服务中很难做到正确。您肯定需要有一种方法通过结构化数据很好地通知客户错误。我想这应该是你所有回应的一部分。您将需要决定将哪些错误发回信息，哪些是您保持沉默并只记录的错误，等等。

3. 很可能你会有一些数据对象来处理你收到的请求和你发送的响应。将它们包装在一个单独的罐子里。添加到这个 jar 接口，由您的控制器实现。还添加这些接口的第二个简单实现，用于调用您的服务。给你，你有一个客户端库。分发它，让您的 Java 客户满意。

4. 即使现在您有一个不错的 Java 客户端库，也不要忘记使用 curl 测试您的服务，并记录如何通过简单调用以这种方式使用它。让您的非 Java 用户满意。

5. 通过模拟或多或少的网络服务器内部结构，有各种用于“单元”测试控制器的库。这些非常有用，但不要仅限于它们。有一个 qa 环境，您可以在其中完全部署您的服务，并且有一个 qa 应用程序，它向 qa 环境上的服务实例发送真正成熟的请求，并分析它们的响应。

6. 尝试在不同的调用中保持简单和一致。例如，每个响应都可以包含具有相同字段的相同“错误”部分，以结构化的编程可用形式提供有关出错的信息。

7. REST 是一个很好的抽象，但有其局限性：在实践中， /delete.json?id=3 对不同的服务可能产生非常不同的影响。不要期望您的客户能够猜测在您的特定情况下“添加”和“删除”的含义，因为他们的猜测可能与您的预期不同。相反，在您的文档中提供一些有关您的服务将在后台执行的操作的信息。不幸的是，我们还没有达到能够通过非常薄的界面知识让组件进行通信的阶段，而不知道它们的内部结构。