身份认证与应用安全 / 系统课时
约定登录请求与响应格式
约定登录请求与响应格式
前后端分离登录先要把“接口长什么样”固定下来,再实现密码校验和 JWT 生成。本篇用独立 DTO 约定请求、成功响应与失败响应,让认证内部逻辑可以变化,而前端只依赖稳定的 HTTP 契约。
学习目标
- 设计只承载登录输入的请求 DTO,避免直接复用用户实体。
- 统一成功与失败响应字段,并明确常见 HTTP 状态码。
- 用固定请求样例验证前后端是否遵守同一份登录契约。
把接口契约与认证实现分开
登录接口可以约定为 POST /api/auth/login。请求只包含前端真正需要提交的凭证;后端完成认证后,只返回调用方后续鉴权所需的数据。数据库字段、密码哈希、用户实体和认证框架对象都不应该直接暴露在接口模型里。
建议把边界控制在三种对象:LoginRequest 表示输入,LoginSuccessResponse 表示成功结果,ApiError 表示失败结果。这样以后即使认证实现从内存用户切换到数据库,或者 JWT 生成策略改变,前端字段也不必跟着内部类型调整。
定义请求和响应 DTO
下面是片段示例,放入已有的 Spring Boot Web 项目中;三个 record 分别保存为同名 Java 文件。它们只负责传输数据,不在 DTO 中执行密码校验或生成令牌。
package com.example.auth.api;
public record LoginRequest(
String username,
String password
) {
}package com.example.auth.api;
public record LoginSuccessResponse(
String accessToken,
String tokenType
) {
public static LoginSuccessResponse bearer(String accessToken) {
return new LoginSuccessResponse(accessToken, "Bearer");
}
}package com.example.auth.api;
public record ApiError(
String code,
String message
) {
}tokenType 固定返回 Bearer,前端即可统一拼接 Authorization: Bearer <JWT>。不要把密码、密码哈希或完整用户实体放进成功响应;如果页面还需要昵称、头像等资料,应由明确的用户资料字段或独立接口提供。
固定成功与失败语义
接口状态码和响应体应同时表达结果,避免所有情况都返回 200 再让前端猜业务字段。一个够用的约定如下。
| 场景 | HTTP 状态 | 响应类型 | 关键字段 |
|---|---|---|---|
| 凭证正确 | 200 |
LoginSuccessResponse |
accessToken、tokenType |
| 用户名或密码错误 | 401 |
ApiError |
code=INVALID_CREDENTIALS |
| 请求体缺失或格式不合法 | 400 |
ApiError |
code=BAD_REQUEST |
成功响应可以保持精简:
{"accessToken":"<JWT>","tokenType":"Bearer"}凭证错误时返回稳定的机器码和可展示消息:
{"code":"INVALID_CREDENTIALS","message":"用户名或密码错误"}前端应优先根据 HTTP 状态和 code 分支,不要依赖中文 message 做程序判断。message 可以调整文案,code 才是稳定协议。
用固定请求验证契约
接口实现完成后,可用一个已存在的有效账号替换 <PASSWORD> 进行验证;<PORT> 是应用实际监听端口,JWT 的实际字符串每次可能不同。
curl -s -X POST http://localhost:<PORT>/api/auth/login -H 'Content-Type: application/json' -d '{"username":"alice","password":"<PASSWORD>"}'预期输出
{"accessToken":"<JWT>","tokenType":"Bearer"}如果前端发送 userName,而后端 DTO 约定的是 username,这种问题应该在接口联调阶段直接修正,而不是让认证服务同时兼容多套字段。稳定的 DTO 和错误码就是前后端之间的边界,认证实现只需要在这个边界内部演进。