1. 先钉死接口契约再动手写代码写注册接口这件事很多人第一反应是打开 IDE 建个 Controller然后一边写一边想字段。我见过太多项目在这个环节翻车前端调了两天发现字段对不上测试提了十几个为什么这里返回 500上线后运维发现日志里全是空指针。真正省时间的做法恰好相反——先把契约写在纸上包括请求字段、返回结构、错误码、幂等规则再开始写第一行业务代码。注册接口看着简单它却是整个账号体系的入口字段定义一旦定下来后面改一次要牵动登录、找回密码、第三方绑定、用户中心一大串模块。这篇文章讲的是「后端系统开发之——创建注册接口」我会把它当成一次完整的实战复盘来做从契约设计、密码存储、表结构与唯一约束、事务与并发、频控加固一直讲到联调自测。适合刚接触后端业务开发、准备写第一个正式接口的朋友也适合做了一两年但一直靠能跑就行撑着的同行——里面有不少地方是踩过坑之后才知道该这么写的。1.1 一个注册请求到底该收哪些字段先把字段分成三类身份凭证、可选资料、上下文信息。身份凭证是必须的通常是手机号或邮箱二选一加一个密码可选资料是昵称、头像、邀请码这类缺了也能创建账号上下文信息是客户端类型、渠道来源、设备标识用来做风控和后期分析一般不参与业务校验。分清楚这三类好处是校验逻辑可以分层身份凭证缺失直接 400可选资料缺失走默认值上下文信息缺失只记一条告警不阻断流程。我见过把邀请码做成必填的接口注册转化率直接掉了三成后来才发现是运营在某次活动页跳转时没带参数。下面这份请求体是我目前项目里用的最小集合可以直接参考{ account: 13800000000, password: Abc123456, nickname: 路人甲, channel: web, inviteCode: XK92A, captchaToken: c_8f3a... }几个细节值得说清楚。account用一个字段同时承载手机号和邮箱靠正则区分类型好处是前端只渲染一个输入框缺点是后端每次都要做类型判断如果你的业务明确只支持手机号那就老老实实叫mobile别为了以后可能支持邮箱提前抽象抽象是有成本的。password只做长度和字符集校验绝不在请求体里做业务语义上的复杂度提示那属于前端体验层的事后端只守住底线。captchaToken这类字段建议单独抽出来别和业务字段混在一起因为它对应的校验逻辑是一次性消耗和幂等、事务的边界完全不同。1.2 返回体与错误码别让前端靠猜返回结构我坚持用统一信封{ code: 0, message: ok, data: { userId: 10231, token: eyJ... }, traceId: a1b2c3d4 }code为 0 表示成功非 0 是业务错误码HTTP 状态码只用来表达传输层语义200/400/401/500不要用 HTTP 状态码承载业务错误否则前端要写一大堆if (status 409)的分支网关层的统一重试策略也会被误导。traceId是我强烈建议加上的字段用户截图报错时你拿着 traceId 能直接定位到那一条完整日志链路排查效率的提升是数量级的。错误码要给区间规划别随手编号区间含义示例0成功01000-1099参数与格式错误1001 账号格式不正确1100-1199业务规则拦截1101 该账号已注册1200-1299频控与风控1201 操作过于频繁1500-1599系统内部异常1500 服务繁忙请稍后重试规划好区间前端可以按百位做统一提示文案后端加新错误码也不至于撞号。1.3 三个最容易被忽略的隐含需求第一是幂等。用户手抖点两下、网络超时自动重试、客户端做了一次重发这些场景在移动端是常态。注册接口如果不做幂等结果就是数据库里出现两条同号账号或者第二条请求报已注册而用户以为自己没注册成功。第二是来源校验。开放公网的注册接口一定会被扫加一个来源白名单或者签名校验能挡掉相当一部分低级脚本。第三是注册成功后的返回内容。要不要直接返回登录 token我的做法是返回理由是省一次登录往返用户体验上顺滑很多代价是注册接口要依赖签发 token 的模块耦合度略高。如果团队对登录态有更严格的要求比如必须二次校验设备指纹那就只返回 userId让前端跳登录页。提示契约定稿后写成一份接口文档并纳入版本管理字段增删要走变更流程。我吃过一次亏某同学为了赶需求悄悄把nickname改成必填结果老版本 App 全量报错。2. 密码存储的取舍算法、参数与那条 72 字节的暗线密码这块是最不该省事的地方也是最容易埋雷的地方。我见过用 MD5 存的、用 MD5 加固定盐存的、用 Base64 当加密的每一种都能在出事后把团队拖进深坑。2.1 为什么自己拼 MD5 加盐基本等于没加哈希算法的核心指标是计算速度。MD5 和 SHA-256 是为快设计的一张消费级显卡每秒能算几十亿次。这意味着攻击者拿到库之后用常见密码字典跑一遍弱密码半小时内就能还原出明文。加盐确实能挡住彩虹表但挡不住针对单个账号的暴力枚举——因为快。真正适合存密码的是慢哈希BCrypt、scrypt、Argon2 这一类设计目标就是故意算得慢而且慢的程度可以通过参数调节。它们内置了每个用户独立的盐输出串里自带算法标识、成本参数和盐值不需要你额外建字段存盐。这一点特别重要自己管理盐的代码十个有八个在某个分支里写错。2.2 成本参数到底该设多少BCrypt 的成本参数是cost每加 1计算耗时翻一倍。常用的cost10在普通云主机上单次哈希大约 50-100ms。这个数值不是拍脑袋定的要结合你的硬件和流量算一笔账。估算逻辑是这样的假设注册加登录合计峰值 300 QPS每次哈希按 80ms 计那么同时处于哈希计算中的请求数为 300 × 0.08 24。这部分是纯 CPU 密集操作一个 4 核机器基本扛不住你会看到 CPU 打满、请求排队、P99 飙到几秒。反过来说如果你现在只有 20 QPS那cost12完全没问题安全性还更高。我给的经验区间是cost10起步实测单次耗时控制在 100ms 以内压测确认 CPU 余量大于 50%。真要更高强度就上 Argon2id 并调内存参数或者把哈希计算挪到独立的线程池/服务里别和业务线程抢资源。还有个参数叫strengthBCryptPasswordEncoder 里的版本默认 10注意它和cost是同一个东西的两种叫法别在配置里写成两个值。2.3 BCrypt 只认前 72 字节这个坑很隐蔽这是我最想强调的一条。BCrypt 的算法设计只处理输入的前 72 个字节超出部分被静默截断。也就是说如果你允许用户设置超长密码第 73 个字节之后的内容完全不参与计算两个前 72 字节相同的密码会被判定为同一个密码。更麻烦的是中文密码——一个汉字在 UTF-8 下占 3 个字节72 字节大约只够 24 个汉字。有些库在超长时会直接抛异常Spring Security 的某些版本就会有些库则默默截断行为不一致。所以我的做法是在参数校验层就把密码长度卡死在 8 到 64 个字符并且明确按字节数再校验一次不超过 72 字节。private static void checkPassword(String pwd) { if (pwd null || pwd.length() 8 || pwd.length() 64) { throw new BizException(1002, 密码长度需在 8-64 个字符之间); } if (pwd.getBytes(StandardCharsets.UTF_8).length 72) { throw new BizException(1002, 密码过于复杂请适当缩短); } }另外补一句pepper全局密钥不是必须的但如果你担心库被拖走后成本参数不够用可以在哈希前拼一段存在配置中心或环境变量里的密钥。代价是密钥轮换时所有存量密码都要重算所以一般只在新项目里上老项目别折腾。3. 表结构与唯一约束把并发问题交给数据库写业务代码的人常有个错觉觉得我在代码里查过了没重复那就不会重复。单线程下这话没错多线程和分布式环境下这行代码等于没写。注册接口的重复账号问题最可靠的兜底方案永远是数据库的唯一索引。3.1 用户表的最小字段集先上一份我认为比较克制、但足够支撑后续扩展的建表语句CREATE TABLE t_user ( id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, account VARCHAR(64) NOT NULL COMMENT 账号手机号或邮箱已归一化, account_type TINYINT NOT NULL DEFAULT 1 COMMENT 1手机号 2邮箱, password_hash VARCHAR(100) NOT NULL, nickname VARCHAR(32) NOT NULL DEFAULT , status TINYINT NOT NULL DEFAULT 1 COMMENT 1正常 2禁用, register_channel VARCHAR(16) NOT NULL DEFAULT , created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, deleted_at BIGINT NOT NULL DEFAULT 0 COMMENT 0 未删除否则为删除时间戳, PRIMARY KEY (id), UNIQUE KEY uk_account (account, deleted_at) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;几个设计理由password_hash给 100 长度是因为 BCrypt 输出固定 60 字符Argon2 可能更长留余量避免以后改表。status不要用布尔值业务早晚会有未激活已冻结已注销这几种状态。时间字段统一用DATETIME并存 UTC别混用时间戳和字符串。3.2 软删除和唯一索引天生打架怎么解如果你直接UNIQUE KEY (account)那用户注销后想重新注册同号就废了——因为那条软删除的记录还占着位置。常见解法有三种第一种是上面用的(account, deleted_at)组合唯一索引删除时把deleted_at写成删除时刻的时间戳。因为未删除记录都是 0(account, 0)只能存在一条符合要求删除后变成(account, 1723...)同号可以再注册一条。这个方案唯一的坑是同一账号被删两次会撞索引所以删除逻辑里要先判断deleted_at 0。第二种是物理删除或者把账号改写比如加后缀实现简单但丢失审计能力我不太推荐。第三种是单独建一张注销账号表做归档主表物理删除。适合合规要求高的场景。3.3 归一化不做唯一索引就是个摆设这是我排查过最气人的一类问题库里出现了13800000000、138 0000 0000、13800000000尾部空格三条记录唯一索引一条都没拦住因为它们在字符串层面确实不相等。所以在进入业务逻辑之前必须做一次归一化手机号去掉所有空格、横线、括号和86前缀邮箱整体转小写严格说只有域名部分大小写不敏感但实践中整体小写更省事且绝大多数服务商不区分账号两端trim。public static String normalize(String raw, int type) { if (raw null) return null; String s raw.trim(); if (type 1) { s s.replaceAll([\\s\\-()], ); if (s.startsWith(86)) s s.substring(3); if (s.startsWith(0086)) s s.substring(4); if (s.length() 13 s.startsWith(86)) s s.substring(2); } else { s s.toLowerCase(Locale.ROOT); } return s; }注意toLowerCase一定要带Locale.ROOT不带的话在土耳其语环境下I会被转成ı这是个真实存在过的经典 bug。4. 接口实现骨架校验、事务、异常三段切骨架理清楚之后代码写起来其实很快。我的分层习惯是把 Controller 做薄、Service 做业务编排、仓储层只碰数据异常统一在一处兜。4.1 参数校验分两层别全塞进注解第一层是格式校验用 Bean Validation 注解就能覆盖非空、长度、正则。这一层的好处是失败信息标准前端好处理。public class RegisterRequest { NotBlank(message 账号不能为空) Size(max 64, message 账号过长) private String account; NotBlank(message 密码不能为空) private String password; Size(max 32, message 昵称过长) private String nickname; private String channel; private String inviteCode; private String captchaToken; }第二层是业务校验放 Service 里做账号格式是否符合手机号/邮箱规则、密码强度是否达标、验证码是否正确、账号是否已存在。为什么不在注解里做完因为业务校验往往要查库、要调缓存、要读配置放在参数绑定阶段会让事务和依赖注入变得很别扭。4.2 事务边界要包住插入 初始化注册不只是插一条用户记录通常还要初始化用户资料、发积分、写注册流水、绑定渠道关系。这些动作要么全成功要么全回滚所以事务边界必须包住它们。Transactional(rollbackFor Exception.class) public RegisterResult register(RegisterRequest req) { String account AccountUtil.normalize(req.getAccount(), type); checkPassword(req.getPassword()); if (userRepo.exists(account)) { throw new BizException(1101, 该账号已注册); } User user new User(); user.setAccount(account); user.setPasswordHash(passwordEncoder.encode(req.getPassword())); user.setNickname(defaultNickname(req.getNickname())); user.setRegisterChannel(req.getChannel()); try { userRepo.insert(user); } catch (DuplicateKeyException e) { throw new BizException(1101, 该账号已注册); } profileService.init(user.getId()); pointService.grantRegisterPoint(user.getId()); return new RegisterResult(user.getId(), tokenService.issue(user.getId())); }注意try-catch只包住 insert别把整个方法体包进去否则后续任何一处抛DuplicateKeyException比如 profile 表自己的唯一约束冲突都会被误判成账号已注册排查起来非常痛苦。4.3 那个 exists 查询到底要不要上面的代码里我先查了一次exists然后插入时又靠唯一索引兜底。有人会问既然唯一索引能兜查这一次不是浪费我的判断是要查但要知道它只是为了体验。查询的作用是让 99% 的重复注册请求走快速失败路径返回一个明确的已注册而不是让它们都触发一次数据库异常。异常路径的成本高得多——要构造异常对象、要回滚事务、日志里还会留一堆堆栈。所以这个查询是优化不是防线防线永远是唯一索引。如果你的接口 QPS 很高这次查询可以改成查缓存但要接受缓存和数据库之间的短暂不一致最终仍以唯一索引为准。4.4 异常统一处理别把堆栈吐给前端用RestControllerAdvice收口所有异常业务异常转成对应的 code未捕获异常统一转 1500 并打日志带上 traceId、入参脱敏后内容。ExceptionHandler(BizException.class) public Result? handleBiz(BizException e) { return Result.fail(e.getCode(), e.getMessage()); } ExceptionHandler(Exception.class) public Result? handleOther(Exception e) { log.error(register error traceId{}, TraceContext.get(), e); return Result.fail(1500, 服务繁忙请稍后重试); }入参日志一定要脱敏。密码、验证码这些字段在打印请求体前要替换成***我见过某次排查问题直接把日志拖出来发群里里面几百条明文密码的场面。5. 一次重复账号的完整排查链路理论讲完说个真实复盘细节做了模糊处理。某次上线后第二天运营反馈有用户在后台看到两个一模一样的手机号只是 id 不同。这条线索足够把整个链路翻一遍。5.1 现象确认到底是数据重复还是展示重复第一步不是改代码是确认现象。我拉了三样东西那两条记录的完整字段、对应时间段的接口访问日志、以及用户的操作轨迹。结果很快出来两条记录创建时间相差 1.2 秒created_at精确到秒级别的差距register_channel一条是web一条是h5。这说明是同一个人在两个端先后点了注册而不是数据同步问题。5.2 逐层排除为什么唯一索引没拦住接下来就是最关键的一步——查索引。执行SHOW CREATE TABLE t_user发现线上表根本没有uk_account这个索引。追问之后才知道当初建表脚本里有但某次加字段的变更脚本是照着旧版本建的把唯一索引漏掉了DDL 执行时也没人核对。这里我要强调排查思路遇到本该被约束住却没约束住的问题第一顺位永远是确认约束是否存在第二顺位才是确认约束是否生效比如字段是否被隐式转换、是否有 NULL。别一上来就怀疑框架、怀疑事务隔离级别那是最费时间的方向。顺便查了下SHOW INDEX FROM t_user确认只有主键。问题定位完成。5.3 修复与验证以及怎么防止再犯修复分三步走先补索引建之前要先清理存量重复数据否则 DDL 直接失败再加应用层的兜底捕获最后把这次事故变成一个可执行的检查项。清理重复数据的 SQL 大致是这样保留每组最早的一条DELETE t1 FROM t_user t1 INNER JOIN t_user t2 ON t1.account t2.account AND t1.id t2.id WHERE t1.deleted_at 0 AND t2.deleted_at 0;加索引用ALTER TABLE t_user ADD UNIQUE KEY uk_account (account, deleted_at)注意大表要评估锁表风险必要时用在线 DDL 工具在低峰期执行。验证阶段我写了一个并发测试脚本开 50 个线程同时用同一个手机号注册期望结果是 1 条成功、49 条返回 1101。修复前这个用例必然失败修复后必须 100% 通过。这个脚本后来被我放进了回归用例集每次改动注册相关代码都跑一遍。至于防止再犯我做的事很朴素把关键索引清单写进发布检查表每次涉及表结构变更发布前必须对照清单核验一遍。检查项验证方式频率账号唯一索引存在SHOW INDEX FROM t_user每次表变更索引列与归一化逻辑一致代码 review每次改动并发重复注册用例通过自动化脚本每次发布存量重复数据为 0定时巡检 SQL每天6. 上线前的加固频控、验证码与那些看不见的成本接口功能跑通只是及格线真正决定它能不能放在公网上的是防护做得够不够。6.1 频控放在网关还是业务层我的答案是两层都放粒度不同。网关层做粗粒度限流比如单 IP 每分钟 60 次目的是挡住明显的脚本扫描成本极低配置几行就完事。业务层做细粒度控制比如同一手机号 60 秒内只能发一次验证码同一设备指纹 24 小时内最多注册 3 个账号这类规则需要读业务数据放网关不合适。业务层频控用 Redis 的滑动窗口或者简单的SET key value NX EX就够了别一上来就上复杂组件。关键在于 key 的设计要能区分维度reg:mobile:{account}、reg:ip:{ip}、reg:device:{deviceId}三个维度任一超限就拦。6.2 注册接口要不要提示该账号已注册这是个产品和技术要一起决策的点。从安全角度直接提示已注册意味着接口可以被用来枚举哪些手机号在你们平台注册过这是实打实的信息泄露。但从业务角度注册页不提示的话用户体验极差——用户输完密码点提交得到一句操作失败然后呢我的实践结论是注册场景直接提示登录和找回密码场景模糊处理。理由是注册页本身就要发验证码验证码环节已经把枚举成本抬得很高了每次枚举都要消耗一条短信而登录接口如果提示密码错误而不是账号不存在攻击者就无法批量判断账号是否存在。这个取舍没有标准答案但要明确写进设计文档别让后人以为你忘了。6.3 注册成功后的异步动作欢迎消息、初始化推荐数据、发券、埋点上报这些动作都不该阻塞注册响应。我的做法是发一条领域事件异步消费。但这里有个坑异步动作失败要不要回滚注册答案通常是不要。注册是主流程发券失败可以补偿不能因为营销系统挂了让用户注册不了。所以异步消费必须做重试和死信处理并且要有对账机制——每天跑一次注册用户数 vs 发券记录数差得多就报警。7. 自测清单让接口在提测前就接近可用我带的项目里注册接口提测前必须自己跑完一份清单这份清单帮我省下了大量来回沟通。7.1 边界用例按这个顺序过一遍用例期望结果正常手机号 合规密码成功返回 userId 和 token手机号带空格、带 86归一化后成功邮箱大小写混写归一化后可登录密码 7 位 / 65 位返回 1002密码 64 个汉字192 字节返回 1002不得静默截断已注册账号重复提交返回 1101同账号并发 50 次1 成功 49 失败验证码错误 / 过期 / 重复使用分别返回对应错误码超频提交返回 1201数据库连接断开返回 1500日志有 traceId最后一条特别容易被忽略。我习惯在测试环境手动停一下数据库连接池看接口返回的是不是友好的 1500而不是一个 500 加一段堆栈。这个动作花不了一分钟但能避免上线后前端拿到看不懂的响应。7.2 压测看什么指标注册接口的压测重点不是吞吐而是哈希计算对 CPU 的影响。我会关注三个数单次请求耗时中位数、P99、以及压测期间机器的 CPU 使用率曲线。如果 P99 是中位数的 5 倍以上基本可以断定是哈希线程池排队或者数据库连接池不够而不是业务逻辑慢。另外要观察 Redis 频控 key 的增长速度如果发现某个 IP 维度产生了海量 key说明限流阈值设得太松需要收紧。最后分享一个我在实际操作中的习惯注册接口的每一次改动我都会把上面那份清单里最靠前的三条和并发那条重新跑一遍不管改动多小。这四条覆盖了归一化、校验、唯一约束和幂等四个最容易出问题的地方跑完心里就踏实了。
