如何快速构建基于Spring4.0的Rest API

Posted 2023-05-10

这是关于使用Spring MVC创建Web API的另一个教程。

准备开始——POM
由于我是一个maven脑残粉，所以这个项目还是基于maven的。现在Spring 4.0 RC2已经发布了，所以我决定使用最新的依赖管理工具。

配置

这个应用可以使用JavaConfig完成配置。我把它切分为下面几个部分：

ServicesConfig（服务配置）

无需扫描组件，配置真的非常简单：
@Configuration
public class ServicesConfig
@Autowired
private AccountRepository accountRepository;

@Bean
public UserService userService()
return new UserService(accountRepository);


@Bean
public PasswordEncoder passwordEncoder()
return NoOpPasswordEncoder.getInstance();


PersistenceConfig（持久层配置）

我们想要一个配置了所有可用仓库的MONGODB配置。在这个简单的应用中我们只用了一个仓库，所以配置也非常的简单

@Configuration
class PersistenceConfig
@Bean
public AccountRepository accountRepository() throws UnknownHostException
return new MongoAccountRepository(mongoTemplate());


@Bean
public MongoDbFactory mongoDbFactory() throws UnknownHostException
return new SimpleMongoDbFactory(new Mongo(), "r");


@Bean
public MongoTemplate mongoTemplate() throws UnknownHostException
MongoTemplate template = new MongoTemplate(mongoDbFactory(), mongoConverter());
return template;


@Bean
public MongoTypeMapper mongoTypeMapper()
return new DefaultMongoTypeMapper(null);


@Bean
public MongoMappingContext mongoMappingContext()
return new MongoMappingContext();


@Bean
public MappingMongoConverter mongoConverter() throws UnknownHostException
MappingMongoConverter converter = new MappingMongoConverter(mongoDbFactory(), mongoMappingContext());
converter.setTypeMapper(mongoTypeMapper());
return converter;


SecurityConfig（安全配置）

理论上，Spring Security 3.2完全可以使用JavaConfig。但对于我这也仅仅是一个理论，所以这里还是选择xml配置的方式：
@Configuration
@ImportResource("classpath:spring-security-context.xml")
public class SecurityConfig
使用这个xml就让API能使用基本的安全机制了。

WebAppInitializer（初始化）

我们不想使用web.xml，所以使用下面的代码配置整个应用：
@Order(2)
public class WebAppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer

@Override
protected String[] getServletMappings()
return new String[]"/";


@Override
protected Class[] getRootConfigClasses()
return new Class[] ServicesConfig.class, PersistenceConfig.class, SecurityConfig.class;


@Override
protected Class[] getServletConfigClasses()
return new Class[] WebMvcConfig.class;


@Override
protected Filter[] getServletFilters()
CharacterEncodingFilter characterEncodingFilter = new CharacterEncodingFilter();
characterEncodingFilter.setEncoding("UTF-8");
characterEncodingFilter.setForceEncoding(true);
return new Filter[] characterEncodingFilter;


@Override
protected void customizeRegistration(ServletRegistration.Dynamic registration)
registration.setInitParameter("spring.profiles.active", "default");


WebAppSecurityInitializer （安全配置初始化）

相对于Spring3，可以使用下面这种更加新颖的特性来完成配置：
@Order(1)
public class WebAppSecurityInitializer extends AbstractSecurityWebApplicationInitializer
WebMvcConfig （Mvc配置）

调度控制器配置。这个也非常简单，仅仅包含了构建一个简单API的最重要配置：
@Configuration
@ComponentScan(basePackages = "pl.codeleak.r" , includeFilters = @Filter(value = Controller.class))
public class WebMvcConfig extends WebMvcConfigurationSupport

private static final String MESSAGE_SOURCE = "/WEB-INF/i18n/messages";

@Override
public RequestMappingHandlerMapping requestMappingHandlerMapping()
RequestMappingHandlerMapping requestMappingHandlerMapping = super.requestMappingHandlerMapping();
requestMappingHandlerMapping.setUseSuffixPatternMatch(false);
requestMappingHandlerMapping.setUseTrailingSlashMatch(false);
return requestMappingHandlerMapping;


@Bean(name = "messageSource")
public MessageSource messageSource()
ReloadableResourceBundleMessageSource messageSource = new ReloadableResourceBundleMessageSource();
messageSource.setBasename(MESSAGE_SOURCE);
messageSource.setCacheSeconds(5);
return messageSource;


@Override
public Validator getValidator()
LocalValidatorFactoryBean validator = new LocalValidatorFactoryBean();
validator.setValidationMessageSource(messageSource());
return validator;


@Override
public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer)
configurer.enable();


这就是需要的配置，非常简单吧！

IndexController （INDEX控制器）
为了验证这个配置是正确的，我创建了一个IndexController。功能非常简单，只是简单地返回“Hello World”，示例代码如下：
@Controller
@RequestMapping("/")
public class IndexController
@RequestMapping
@ResponseBody
public String index()
return "This is an API endpoint.";


如果运行一下这个应用，就能够在浏览器中看到返回的“Hello World”文本。

构建API
UserService
为了完成Spring安全框架配置，还需要完成另一个部分：实现之前创建的UserService。
public class UserService implements UserDetailsService
private AccountRepository accountRepository;

public UserService(AccountRepository accountRepository)
this.accountRepository = accountRepository;


@Override
public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException
Account account = accountRepository.findByEmail(username);
if(account == null)
throw new UsernameNotFoundException("user not found");

return createUser(account);


public void signin(Account account)
SecurityContextHolder.getContext().setAuthentication(authenticate(account));


private Authentication authenticate(Account account)
return new UsernamePasswordAuthenticationToken(createUser(account), null, Collections.singleton(createAuthority(account)));


private User createUser(Account account)
return new User(account.getEmail(), account.getPassword(), Collections.singleton(createAuthority(account)));


private GrantedAuthority createAuthority(Account account)
return new SimpleGrantedAuthority(account.getRole());


构建一个API节点需要处理三个方法：获取当前登陆用户、获取所有用户（可能不是太安全）、创建一个新账户。那么我们就按照这个步骤来进行吧。
Account

Account 将会是我们的第一个Mongo文档。同样也是非常简单：
@SuppressWarnings("serial")
@Document
public class Account implements java.io.Serializable

@Id
private String objectId;

@Email
@Indexed(unique = true)
private String email;

@JsonIgnore
@NotBlank
private String password;

private String role = "ROLE_USER";

private Account()



public Account(String email, String password, String role)
this.email = email;
this.password = password;
this.role = role;


// getters and setters

Repository

先创建一个接口：
public interface AccountRepository
Account save(Account account);

List findAll();

Account findByEmail(String email);

接下来创建它的Mongo实现：

public class MongoAccountRepository implements AccountRepository

private MongoTemplate mongoTemplate;

public MongoAccountRepository(MongoTemplate mongoTemplate)
this.mongoTemplate = mongoTemplate;


@Override
public Account save(Account account)
mongoTemplate.save(account);
return account;


@Override
public List findAll()
return mongoTemplate.findAll(Account.class);


@Override
public Account findByEmail(String email)
return mongoTemplate.findOne(Query.query(Criteria.where("email").is(email)), Account.class);



API控制器
功能快要完成了。我们需要将内容提供给用户，所以需要创建自己的节点：
@Controller
@RequestMapping("api/account")
class AccountController

private AccountRepository accountRepository;

@Autowired
public AccountController(AccountRepository accountRepository)
this.accountRepository = accountRepository;


@RequestMapping(value = "current", method = RequestMethod.GET)
@ResponseStatus(value = HttpStatus.OK)
@ResponseBody
@PreAuthorize(value = "isAuthenticated()")
public Account current(Principal principal)
Assert.notNull(principal);
return accountRepository.findByEmail(principal.getName());


@RequestMapping(method = RequestMethod.GET)
@ResponseStatus(value = HttpStatus.OK)
@ResponseBody
@PreAuthorize(value = "isAuthenticated()")
public Accounts list()
List accounts = accountRepository.findAll();
return new Accounts(accounts);


@RequestMapping(method = RequestMethod.POST)
@ResponseStatus(value = HttpStatus.CREATED)
@ResponseBody
@PreAuthorize(value = "permitAll()")
public Account create(@Valid Account account)
accountRepository.save(account);
return account;


private class Accounts extends ArrayList
public Accounts(List accounts)
super(accounts);



我希望你能明白：因为需要直接连接数据库，所以没有对密码进行编码。如果你比较在意这些小细节，那么可以稍后修改。目前这种方式是OK的。

完成
最后我考虑到还需要一个错误处理器，这样用户就可以看到JSON格式的错误信息而不是html。使用Spring Mvc以及@ControllerAdvice很容易实现这一点：
@ControllerAdvice
public class ErrorHandler

@ExceptionHandler(value = Exception.class)
@ResponseStatus(HttpStatus.BAD_REQUEST)
@ResponseBody
public ErrorResponse errorResponse(Exception exception)
return new ErrorResponse(exception.getMessage());




public class ErrorResponse
private String message;
public ErrorResponse(String message)
this.message = message;

public String getMessage()
return message;

参考技术A 这个应用可以使用JavaConfig完成配置。我把它切分为下面几个部分：
ServicesConfig（服务配置）
无需扫描组件，配置真的非常简单：

@Configuration
public class ServicesConfig
@Autowired
private AccountRepository accountRepository;

@Bean
public UserService userService()
return new UserService(accountRepository);


@Bean
public PasswordEncoder passwordEncoder()
return NoOpPasswordEncoder.getInstance();



PersistenceConfig（持久层配置）
我们想要一个配置了所有可用仓库的MONGODB配置。在这个简单的应用中我们只用了一个仓库，所以配置也非常的简单：

@Configuration
class PersistenceConfig
@Bean
public AccountRepository accountRepository() throws UnknownHostException
return new MongoAccountRepository(mongoTemplate());


@Bean
public MongoDbFactory mongoDbFactory() throws UnknownHostException
return new SimpleMongoDbFactory(new Mongo(), "r");


@Bean
public MongoTemplate mongoTemplate() throws UnknownHostException
MongoTemplate template = new MongoTemplate(mongoDbFactory(), mongoConverter());
return template;


@Bean
public MongoTypeMapper mongoTypeMapper()
return new DefaultMongoTypeMapper(null);


@Bean
public MongoMappingContext mongoMappingContext()
return new MongoMappingContext();


@Bean
public MappingMongoConverter mongoConverter() throws UnknownHostException
MappingMongoConverter converter = new MappingMongoConverter(mongoDbFactory(), mongoMappingContext());
converter.setTypeMapper(mongoTypeMapper());
return converter;



SecurityConfig（安全配置）
理论上，Spring Security 3.2完全可以使用JavaConfig。但对于我这也仅仅是一个理论，所以这里还是选择xml配置的方式：

@Configuration
@ImportResource("classpath:spring-security-context.xml")
public class SecurityConfig

使用这个xml就让API能使用基本的安全机制了。
WebAppInitializer（初始化）
我们不想使用web.xml，所以使用下面的代码配置整个应用：

@Order(2)
public class WebAppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer

@Override
protected String[] getServletMappings()
return new String[]"/";


@Override
protected Class[] getRootConfigClasses()
return new Class[] ServicesConfig.class, PersistenceConfig.class, SecurityConfig.class;


@Override
protected Class[] getServletConfigClasses()
return new Class[] WebMvcConfig.class;


@Override
protected Filter[] getServletFilters()
CharacterEncodingFilter characterEncodingFilter = new CharacterEncodingFilter();
characterEncodingFilter.setEncoding("UTF-8");
characterEncodingFilter.setForceEncoding(true);
return new Filter[] characterEncodingFilter;


@Override
protected void customizeRegistration(ServletRegistration.Dynamic registration)
registration.setInitParameter("spring.profiles.active", "default");



WebAppSecurityInitializer （安全配置初始化）
相对于Spring3，可以使用下面这种更加新颖的特性来完成配置

Spring Boot整合Swagger2构建RESTful API

Swagger是一款可以快速生成符合RESTful风格API并进行在线调试的插件。本文将介绍如何在Spring Boot中整合Swagger。

在此之前，我们先聊聊什么是REST。REST实际上为Representational State Transfer的缩写，翻译为“表现层状态转化” 。如果一个架构符合REST 原则，就称它为RESTful架构。

实际上，“表现层状态转化”省略了主语，完整的说应该是“资源表现层状态转化”。什么是资源（Resource）？资源指的是网络中信息的表现形式，比如一段文本，一首歌，一个视频文件等等；什么是表现层（Reresentational）？表现层即资源的展现在你面前的形式，比如文本可以是JSON格式的，也可以是XML形式的，甚至为二进制形式的。图片可以是gif，也可以是PNG；什么是状态转换（State Transfer）？用户可使用URL通过HTTP协议来获取各种资源，HTTP协议包含了一些操作资源的方法，比如：GET 用来获取资源， POST 用来新建资源 , PUT 用来更新资源， DELETE 用来删除资源， PATCH 用来更新资源的部分属性。通过这些HTTP协议的方法来操作资源的过程即为状态转换。

下面对比下传统URL请求和RESTful风格请求的区别：

描述	传统请求	方法	RESTful请求	方法
查询	/user/query?name=mrbird	GET	/user?name=mrbird	GET
详情	/user/getInfo?id=1	GET	/user/1	GET
创建	/user/create?name=mrbird	POST	/user	POST
修改	/user/update?name=mrbird&id=1	POST	/user/1	PUT
删除	/user/delete?id=1	GET	/user/1	DELETE

从上面这张表，我们大致可以总结下传统请求和RESTful请求的几个区别：

1. 传统请求通过URL来描述行为，如create，delete等；RESTful请求通过URL来描述资源。

2. RESTful请求通过HTTP请求的方法来描述行为，比如DELETE，POST，PUT等，并且使用HTTP状态码来表示不同的结果。

3. RESTful请求通过JSON来交换数据。

RESTful只是一种风格，并不是一种强制性的标准。

引入Swagger依赖

本文使用的Swagger版本为2.6.1：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.1</version>
</dependency>

 

配置SwaggerConfig

使用JavaConfig的形式配置Swagger：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
?
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
?
@Configuration
@EnableSwagger2
public class SwaggerConfig 
    @Bean
    public Docket buildDocket() 
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(buildApiInf())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
            .paths(PathSelectors.any())
            .build();
    
    private ApiInfo buildApiInf() 
        return new ApiInfoBuilder()
            .title("系统RESTful API文档")
            .contact(new Contact("mrbird", "https://mrbird.cc", "[e-mail]"))
            .version("1.0")
            .build();
    

 

在配置类中添加@EnableSwagger2注解来启用Swagger2，apis()定义了扫描的包路径。配置较为简单，其他不做过多说明。

Swagger常用注解

• @Api：修饰整个类，描述Controller的作用；

• @ApiOperation：描述一个类的一个方法，或者说一个接口；

• @ApiParam：单个参数描述；

• @ApiModel：用对象来接收参数；

• @ApiProperty：用对象接收参数时，描述对象的一个字段；

• @ApiResponse：HTTP响应其中1个描述；

• @ApiResponses：HTTP响应整体描述；

• @ApiIgnore：使用该注解忽略这个API；

• @ApiError ：发生错误返回的信息；

• @ApiImplicitParam：一个请求参数；

• @ApiImplicitParams：多个请求参数。

编写RESTful API接口

Spring Boot中包含了一些注解，对应于HTTP协议中的方法：

• @GetMapping对应HTTP中的GET方法；

• @PostMapping对应HTTP中的POST方法；

• @PutMapping对应HTTP中的PUT方法；

• @DeleteMapping对应HTTP中的DELETE方法；

• @PatchMapping对应HTTP中的PATCH方法。

我们使用这些注解来编写一个RESTful测试Controller：

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
?
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;
?
import com.example.demo.domain.User;
?
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import springfox.documentation.annotations.ApiIgnore;
?
@Api(value = "用户Controller")
@Controller
@RequestMapping("user")
public class UserController 
?
    @ApiIgnore
    @GetMapping("hello")
    public @ResponseBody String hello() 
        return "hello";
    
?
    @ApiOperation(value = "获取用户信息", notes = "根据用户id获取用户信息")
    @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long", paramType = "path")
    @GetMapping("/id")
    public @ResponseBody User getUserById(@PathVariable(value = "id") Long id) 
        User user = new User();
        user.setId(id);
        user.setName("mrbird");
        user.setAge(25);
        return user;
    
?
    @ApiOperation(value = "获取用户列表", notes = "获取用户列表")
    @GetMapping("/list")
    public @ResponseBody List<User> getUserList() 
        List<User> list = new ArrayList<>();
        User user1 = new User();
        user1.setId(1l);
        user1.setName("mrbird");
        user1.setAge(25);
        list.add(user1);
        User user2 = new User();
        user2.setId(2l);
        user2.setName("scott");
        user2.setAge(29);
        list.add(user2);
        return list;
    
?
    @ApiOperation(value = "新增用户", notes = "根据用户实体创建用户")
    @ApiImplicitParam(name = "user", value = "用户实体", required = true, dataType = "User")
    @PostMapping("/add")
    public @ResponseBody Map<String, Object> addUser(@RequestBody User user) 
        Map<String, Object> map = new HashMap<>();
        map.put("result", "success");
        return map;
    
?
    @ApiOperation(value = "删除用户", notes = "根据用户id删除用户")
    @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long", paramType = "path")
    @DeleteMapping("/id")
    public @ResponseBody Map<String, Object> deleteUser(@PathVariable(value = "id") Long id) 
        Map<String, Object> map = new HashMap<>();
        map.put("result", "success");
        return map;
    
?
    @ApiOperation(value = "更新用户", notes = "根据用户id更新用户")
    @ApiImplicitParams(
        @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long", paramType = "path"),
        @ApiImplicitParam(name = "user", value = "用户实体", required = true, dataType = "User") )
    @PutMapping("/id")
    public @ResponseBody Map<String, Object> updateUser(@PathVariable(value = "id") Long id, @RequestBody User user) 
        Map<String, Object> map = new HashMap<>();
        map.put("result", "success");
        return map;
    
?

 

对于不需要生成API的方法或者类，只需要在上面添加@ApiIgnore注解即可。