身份认证与应用安全 / 系统课时

约定登录请求与响应格式

约定登录请求与响应格式

前后端分离登录先要把“接口长什么样”固定下来,再实现密码校验和 JWT 生成。本篇用独立 DTO 约定请求、成功响应与失败响应,让认证内部逻辑可以变化,而前端只依赖稳定的 HTTP 契约。

学习目标

  • 设计只承载登录输入的请求 DTO,避免直接复用用户实体。
  • 统一成功与失败响应字段,并明确常见 HTTP 状态码。
  • 用固定请求样例验证前后端是否遵守同一份登录契约。

把接口契约与认证实现分开

登录接口可以约定为 POST /api/auth/login。请求只包含前端真正需要提交的凭证;后端完成认证后,只返回调用方后续鉴权所需的数据。数据库字段、密码哈希、用户实体和认证框架对象都不应该直接暴露在接口模型里。

建议把边界控制在三种对象:LoginRequest 表示输入,LoginSuccessResponse 表示成功结果,ApiError 表示失败结果。这样以后即使认证实现从内存用户切换到数据库,或者 JWT 生成策略改变,前端字段也不必跟着内部类型调整。

定义请求和响应 DTO

下面是片段示例,放入已有的 Spring Boot Web 项目中;三个 record 分别保存为同名 Java 文件。它们只负责传输数据,不在 DTO 中执行密码校验或生成令牌。

java
package com.example.auth.api;

public record LoginRequest(
        String username,
        String password
) {
}
java
package com.example.auth.api;

public record LoginSuccessResponse(
        String accessToken,
        String tokenType
) {
    public static LoginSuccessResponse bearer(String accessToken) {
        return new LoginSuccessResponse(accessToken, "Bearer");
    }
}
java
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

成功响应可以保持精简:

json
{"accessToken":"<JWT>","tokenType":"Bearer"}

凭证错误时返回稳定的机器码和可展示消息:

json
{"code":"INVALID_CREDENTIALS","message":"用户名或密码错误"}

前端应优先根据 HTTP 状态和 code 分支,不要依赖中文 message 做程序判断。message 可以调整文案,code 才是稳定协议。

用固定请求验证契约

接口实现完成后,可用一个已存在的有效账号替换 <PASSWORD> 进行验证;<PORT> 是应用实际监听端口,JWT 的实际字符串每次可能不同。

bash
curl -s -X POST http://localhost:<PORT>/api/auth/login -H 'Content-Type: application/json' -d '{"username":"alice","password":"<PASSWORD>"}'

预期输出

json
{"accessToken":"<JWT>","tokenType":"Bearer"}

如果前端发送 userName,而后端 DTO 约定的是 username,这种问题应该在接口联调阶段直接修正,而不是让认证服务同时兼容多套字段。稳定的 DTO 和错误码就是前后端之间的边界,认证实现只需要在这个边界内部演进。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

约定登录请求与响应格式

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通