web-services - 将现有 API 公开为 Web 服务

Question

我目前正在处理一项将 API 公开为 Web 服务的任务。这里的想法是将 JAR 文件中的现有业务逻辑打包到 WAR 文件中，并将 WAR 文件公开为将返回自由格式 XML 字符串的 Web 服务。当我们将现有 API 公开为 Web 服务时，我们提供返回的 XML 字符串数据的 XSD 和 WSDL 文件就足够了吗？这是惯例还是标准做法？

Answer 1

这取决于您使用的是 SOAP 还是 REST。 SOAP 更严格；因此，您更希望拥有一个 WSDL 文件来生成与 API 接口(interface)的类。

另一方面，如果您使用的是 REST，那么仅公开一个 RESTful URI 就足以满足具有统一接口(interface)的 RESTful Web 服务的约束。

REST 往往比 SOAP 获得更多的支持，因为它是一种宽松的架构风格。我更喜欢这种方法，如果您不熟悉开发 Web 服务，我会推荐这种方法。

根据您使用的语言，我假设是 Java，您可以使用 ReSTLets 或 Spring 3.0 的 REST 框架来帮助您构建 RESTful Web 服务。这些工具确实使这项工作变得更容易，并帮助您遵守 6 Constraints of a RESTful Web Service并满足4 Key Goals .

更新:

假设您已经有现有的、面向对象的代码，并假设您想将该代码公开为 REST API，使用 Spring 3.0 MVC，创建一个将包装现有包的 Controller 子类:

示例 GET :

资源:Javadocs for Jackson's ObjectMapper POJO/JSON Marshaller

 // this is the wrapper around your existing Java packages.  
 @Controller
 public class UserController {

     protected static final DATA_TYPE = "json";

     // In REST, GET method is used to retrieve data with no side effects, 
         // meaning that no changes are made to the data on the server.
     @RequestMapping(value="/users/{username}", method=RequestMethod.GET)
     public void getUserData(@PathVariable("username") String userName, Model model) {

         // this is your existing class
         UserDataService userDataService = new UserDataService();

         // assume you have a class User, and getUserDetails gives you that POJO object.
         User user = userDataService.getUserDetails(username);


         // marshal the User object to JSON, using Jackson, and write as output in response
         ObjectMapper mapper = new ObjectMapper();
         mapper.writeValue(response.getWriter(), user);

     }
 }

 // assume you have an existing POJO class called User
 class User implements Serializable {

     String username;
     String age;
     String birthday;
     String mood;

     String getMood() { return this.mood; }
     String getBirthday() { return this.birthday; }
     String getAge() { return this.age; }
     String getUsername() { return this.username; }

     String setMood(String mood) { this.mood = mood; }
     String setBirthday(String birthday) { this.birthday = birthday; }
     String setAge(String age) { this.age = age; }
     String setUsername(String username) { this.username = username; }
}

请求 :

http://api.example.com:8080/users/jmort253/

回复:

{ 
    "username":"jmort253",
    "mood":"good",
    "age":"not too old and not too young",
    "birthday","Jan 1, 1900"
}

XML 代替 JSON :

返回 XML 和返回 JSON 之间的主要区别在于使用的编码器。使用 javax.xml.bind.annotations，您可以在 POJO 类上放置注释，以便编码器可以将其转换为 XML，从而将您从手动手动编码 XML 的细节中解放出来:

Using javax.xml.bind.annotations to convert Java Objects to XML and XSD .如果您认为这是 REST Web 服务的要求，该资源还解释了如何生成 XML 模式。

 @XmlRootElement
 class User implements Serializable {

     String username;
     String age;
     String birthday;
     String mood;

     String getMood() { return this.mood; }
     String getBirthday() { return this.birthday; }
     String getAge() { return this.age; }
     String getUsername() { return this.username; }

     String setMood(String mood) { this.mood = mood; }
     String setBirthday(String birthday) { this.birthday = birthday; }
     String setAge(String age) { this.age = age; }
     String setUsername(String username) { this.username = username; }
}

不要使用 Jackson API 的 ObjectMapper 类将 POJO 类编码为 JSON，而是使用 javax.xml.bind.annotations 包代替 ObjectMapper:

JAXBContext context = JAXBContext.newInstance(User.class);
Marshaller marshaller = context.createMarshaller();

// pretty print XML
marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true); 
marshaller.marshal(user, System.out);

除了其他资源，本文还有一些使用 JAXB to deserialize an ArrayList of POJO objects to XML 的示例.

在使用 REST Web 服务包装器时，我的最后一个建议是将您的日志记录级别设置为“ALL”或“DEBUG”。我发现这有助于我更轻松地确定设置 Web 服务时遇到的任何问题的根本原因。这些库本身将输出有用的调试消息，以帮助您解决配置问题，例如缺少依赖项、缺少注释以及您在处理转换为 XML/JSON 过程或设置 Spring 3.0 时可能遇到的其他问题。

一旦您设置了统一接口(interface)并且您可以发出 GET 请求并接收响应，您就可以将日志记录级别设置回之前的 INFO 或 WARN 级别。