Rest API设计

刺骨的言语ヽ痛彻心扉 2022-03-02 15:24 261阅读 0赞

# rest api 设计 #

分布式应用程序

*  rest 方式 http协议, 应用更为广泛, 前台应用(app, web)通过 http协议 调用后台服务
    
     *  RestTemplate
 *  dubbo tcp 例如后台的几个应用之间进行调用

## 1. 如何开发 rest api ##

思想是把网络上的服务都看做一个个的资源，每个资源有一个唯一地址，可以对于这个资源进行增删改查

## 四种请求方式 ##

把不同 http 的请求方式对应到不同的增删改查操作上  
\* get - 对资源的查询  
\* post - 对资源的新增 (不幂等)  
\* put - 对资源的修改 (幂等)  
\* delete - 对资源的删除

## Restful 风格 ##

Restful 风格即请求路径都一样, 通过请求方式加以区分

服务器端提供服务

@RestController
    public class UserController { 
       @GetMapping("/user/{id}")
       public User findById(@PathVariable("id") int id) { 
           User user = new User();
           user.setId(id);
           user.setUsername("张三");
           user.setAge(18);
           return user;
       }
    
       @PostMapping("/user")
       public ResponseEntity add(@RequestBody User user) {  // @RequestBody 用来将请求体内 json 格式的数据转换为 java 对象
           System.out.println(user);
           HttpHeaders headers = new HttpHeaders();
           headers.setContentType(MediaType.APPLICATION_JSON_UTF8);
           headers.set("aaaa", "bbbb");
           ResponseEntity response = new ResponseEntity(user, headers, HttpStatus.NOT_FOUND);
           return response;
       }
    
       @PutMapping("/user/{id}")
       public User update(@PathVariable("id") int id, @RequestBody User user) { 
           System.out.println(id);
           System.out.println(user);
           return user;
       }
    
       @DeleteMapping("/user/{id}")
       public Integer add(@PathVariable("id") int id) { 
           System.out.println("删除了用户:" + id);
           return id;
       }
    }

客户端访问服务器端  
通过不同的方法访问不同的请求类型

*  template.getForObject();
 *  template.delete();
 *  template.postForObject();
 *  template.put();  
    这四个方法第一个参数都为url,其中get 与post要在参数末尾传入一个返回类型的.class类型。

RestTemplate template = new RestTemplate();
            User user = template.getForObject("http://localhost:8080/user/id=1", User.class);
            System.out.println(user);

## 幂等 ##

当给一个资源发送多次请求时，请求结果不受请求次数的影响，称之为幂等的

product 商品表  
修改商品的库存 store 5

update product set store = store - 1 where id = 2  -- 非幂等

update product set store = 4 where id = 2  -- 幂等

*  新增总是不幂等的
 *  但是设计修改方法时，建议设计为幂等的

## jwt ##

json web tokens (令牌)

依赖

<dependency>
                <groupId>io.jsonwebtoken</groupId>
                <artifactId>jjwt-impl</artifactId>
                <version>0.10.5</version>
            </dependency>
            <dependency>
                <groupId>io.jsonwebtoken</groupId>
                <artifactId>jjwt-jackson</artifactId>
                <version>0.10.5</version>
            </dependency>

### 1. 创建令牌 ###

生成一个秘钥对象

SecretKey secretKey = Keys.secretKeyFor(SignatureAlgorithm.HS256);
            Base64Encoder encoder = new Base64Encoder();
            System.out.println(encoder.encode(secretKey.getEncoded()));

要保证使用同一个秘钥对象。

// token 是最后生成的令牌（包含了 内容 claims, 签名(signature), 算法名称(alg)）
    String token = Jwts.builder()
    	//内容部分
    	.claim("sub", "1")
    	//过期时间
    	.claim("exp", "1552715553") // 秒
    	// 签名算法
    	.signWith(SignatureAlgorithm.HS256, "ZYUf0Oym0Lhi9V7f6ML6tXcv0HvGH7YnuhbGhk8Y/+U=")
    	.compact();

设置内容和时间可以以使用下边方法

String token = Jwts.builder()
    	// 内容部分
    	.setSubject("1") // claims("sub", "1")
    	.setExpiration(new Date(System.currentTimeMillis()+60*1000)) // 设置 1 分钟后过期
    	// 签名算法
    	.signWith(SignatureAlgorithm.HS256, "ZYUf0Oym0Lhi9V7f6ML6tXcv0HvGH7YnuhbGhk8Y/+U=")
    	.compact();

### 2. 验证令牌 ###

// 解析器
    Jwts.parser()
    		// 设置秘钥
    		.setSigningKey("ZYUf0Oym0Lhi9V7f6ML6tXcv0HvGH7YnuhbGhk8Y/+U=")
    		.parse(token);

好处：

*  无需将用户的认证信息，存储于服务器端的 session 中， 服务器端不会使用 session 了，称之为 stateless 无状态
 *  stateless 可以让服务器的扩展性得到极大提高
 *  经常用在前后台分离的开发中
 *  令牌信息放在请求头中，不存在跨域问题  
    格式

请求头名            值
    Authorization      "Bearer 令牌"

*  令牌中还可以存储其他信息

Jwts.builder().claims("名字", 值)

*  注意1，名字不要和预定义的名称冲突，sub，exp
 *  注意2，不要存储敏感信息（如密码）
 *  获取令牌信息

Jwt jwt = Jwts.parser()setSigningKey(秘钥)parse(令牌);
    Claims c = (Claims)jwt.getBody();
    c.get("名字");

## 应用中的例子 ##

### 获取令牌响应的格式 ###

ResponseEntity (内部包含了响应的各个组成部分)  
new ResponseEntity(响应体, 响应头, 状态码);

*  状态码
    
     *  200 正常
     *  400 请求参数问题
     *  401 认证失败（登录失败）
     *  403 没有权限
     *  404 资源不存在
     *  405 请求方法不支持 (例如，只支持post，使用get访问)
 *  响应头
 *  响应体
    
     *  一般在rest api 都是 json 格式
 *  响应体给一个java 对象即可，最后会转为 json
 *  响应头是一个map 集合，内含多个键值，有很多预定义的键值(content-type)
 *  状态码 是一个枚举值 HttpStatus
 *  控制器方法内返回这个 ResponseEntity 对象

给用户发令牌

@RestController
    @RequestMapping("/gunsApi")
    public class ApiController extends BaseController { 
    	//固定的秘钥
        public final static String key = "Ihor9JW8e9A1hG6McNAEXkLyvS6jo3LSOAK2Fl5h0Fw=";
        @Autowired
        private UserDao userDao;
        @Autowired
        private RoleDao roleDao;
        /** * 获取 token */
        @PostMapping("/auth")
        public ResponseEntity<Map<String, String>> auth(String username, String password) { 
            // 1. 获取用户
            User dbUser = userDao.selectByAccount(username);
            Map<String, String> body = new HashMap<>();
            // 2. 检查用户存在
            if( dbUser == null ){ 
                body.put("message", "该用户不存在");
                return new ResponseEntity<Map<String, String>>(body, HttpStatus.UNAUTHORIZED);
            }
            // 3. 检查密码是否正确
            if( ! BCrypt.checkpw(password, dbUser.getPassword())) { 
                body.put("message", "密码不正确");
                return new ResponseEntity<Map<String, String>>(body, HttpStatus.UNAUTHORIZED);
            }
            //4. 获取用户的角色信息
            String roleId = dbUser.getRoleId();// 获取用户的角色, 中间用, 分隔
            String[] split = roleId.split(",");
            List<String> roleNames = new ArrayList<>();
            for (String rid : split) { 
                String name = roleDao.selectName(Long.valueOf(rid));
                roleNames.add(name);
            }
    
            // 5. 发放 access token， 必须包含 subject 和 过期时间
            String token = Jwts.builder()
                    .setSubject(String.valueOf(dbUser.getUserId())) // subject 一般唯一
                    .setExpiration(new Date(System.currentTimeMillis() + 1800 * 1000))
                    .claim("name", dbUser.getName())  
                    .claim("roleNames", roleNames.toString())
                    .signWith(SignatureAlgorithm.HS256, key)
                    .compact();
            body.put("access_token", token);
            return new ResponseEntity<>(body, HttpStatus.OK);
        }
    }

验证用户令牌

public class RestApiInteceptor implements HandlerInterceptor { 
        @Override
        public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { 
            // 1. 如果是获取 token 路径，放行
            // request.getRequestURI() 获取当前请求路径
            if(request.getRequestURI().equals("/gunsApi/auth")) { 
                return true;
            }
           // 2.判断令牌是否合法
            String authorization = request.getHeader("Authorization");
            if(authorization == null || !authorization.startsWith("Bearer ")) { 
                response.setStatus(401);
                response.setCharacterEncoding("utf-8");
                response.getWriter().write("{\"message\":\"令牌不存在或格式不对\"}");
                return false;
            }
    		// 3.从请求头中拿令牌
            String token = authorization.substring(7);
            // 4. 解析 token 出异常说明被篡改,或是超时等
            try { 
                Jwt jwt = Jwts.parser().setSigningKey(ApiController.key).parse(token);
    
                // 获取令牌的内容部分
                Claims body = (Claims) jwt.getBody();
                System.out.println("用户的姓名：" + body.get("name"));
                System.out.println("用户的角色：" + body.get("roleNames"));
            } catch (ExpiredJwtException | MalformedJwtException | SignatureException | IllegalArgumentException e) { 
                response.setStatus(401);
                response.setCharacterEncoding("utf-8");
                response.getWriter().write("{\"message\":\"令牌无效\"}");
                return false;
            }
    
            return true;
        }
    }