上午同事发来一条接口报错截图红字写着“城市编码不能为空”。签名串明明按文档用MD5算了参数也都拼上了结果请求还是被拦在业务校验这层。这类问题在维护教育类终端App的接口时太典型了前半段是签名算法后半段是业务参数两者经常缠在一起同时报错。今天借这个真实报错把MD5签名算法的完整计算过程、城市编码参数为什么不能为空、以及如何定位修复整个链路一次性讲清楚。先说结论这个报错出现的时候八成不是MD5算法本身算错了而是城市编码这个字段在某一环被丢掉或者没有参与签名。问题可能出在客户端参数拼接、服务端验签顺序、甚至是定位SDK拿不到城市信息。下面从签名机制的设计逻辑开始拆。1. 签名机制与城市编码在接口交互中的定位1.1 为什么接口要加签名在现网环境里接口一旦暴露就会面对各种伪造请求、重放攻击、参数篡改。最朴素也最常用的防御手段就是给请求加签名sign。签名的作用就像快递包裹上的封条收件人拿到包裹先检查封条是否完整如果封条对不上直接拒收。接口签名也是同一个逻辑客户端把请求参数按约定规则拼接成一个字符串用MD5这类哈希算法算出一个定长的摘要连同请求一起发给服务端。服务端拿到后用同样的规则重新计算一次摘要两个摘要一致才认为请求是合法的、参数没有被改过。签名能解决几个实际痛点防篡改参数在传输过程中被改动服务端重算的签名就会与原签名不一致直接拒绝。身份校验签名中通常会混入密钥key只有持有相同密钥的客户端才能算出合法签名。防重放签名串里带上时间戳服务端校验时间窗口超过一定时效的请求直接丢弃。对于“某东方”这类带内容分发、区域服务的产品来说签名校验就是网关前面的第一道门这道门没通过后面根本不用谈业务逻辑。1.2 城市编码是什么为什么它参与签名城市编码在接口参数里通常是cityCode一个六位数字的行政区划代码。比如某个市的代码是110100结构上前两位是省级中间两位是市级后两位是区县级。这套编码在电商、本地服务、教育内容分发里非常常见原因很简单数据要分区。同一个App在不同城市打开首页推荐的内容、课程的价格、线下活动的列表都可能不一样。服务端拿到cityCode之后才能决定路由到哪个区域服务节点、查哪张数据分片表、返回哪套配置。如果没有城市编码服务端要么返回默认内容要么直接报错而“城市编码不能为空”就是后者。问题在于cityCode不是只作为业务参数存在。很多签名规则要求“所有参与请求的业务参数都参与签名”cityCode自然也得拼进签名串。于是它承担了两个职责既要在签名时被计算进去又要在业务参数里传给服务端。这就容易出现数据不一致的情况——签名时用了cityCode110100实际请求体里没传cityCode或者传成了空字符串服务端验签时用请求体里的空值去重算签名肯定对不上又或者签名是对的但业务参数校验发现城市编码为空。1.3 常见签名流程与“城市编码不能为空”的触发位置一个典型的签名接口交互流程是这样的客户端收集本次请求的全部参数包括业务参数cityCode、goodsId、timestamp等。对参数名按字典序排序排除sign本身和空值参数。将参数拼接成key1value1key2value2格式的字符串。在拼接串末尾附上密钥key形成最终待签名串。对待签名串做MD5计算结果转成32位小写十六进制字符串得到sign。请求发送时带上所有业务参数和sign。服务端拿到请求后先按同一套规则重算sign不一致则拒绝。签名校验通过后进入业务参数校验检查cityCode等必填字段。“城市编码不能为空”这个报错可能出现在第7步也可能出现在第8步。如果服务端在验签时发现请求体里的cityCode为空但签名串里带上了cityCode的占位值那么重算出来的签名和客户端传的sign不一致就会报签名错误如果签名时压根没拼cityCode签名校验能过但进入业务校验时发现这个字段为空就会报“城市编码不能为空”。所以排查的第一步是分清报错节点而这一步可以通过观察返回报文结构来判断后面会细说。2. MD5签名算法原理与完整计算过程2.1 MD5的核心原理MD5Message-Digest Algorithm 5是一种广泛使用的哈希算法输入任意长度的字节串输出固定128位16字节的摘要。它的设计目标是不可逆、雪崩效应明显——原文只要改动一个字符输出的摘要面目全非。MD5的计算过程分为四步补位对原始消息进行填充使消息长度以比特计对512取模等于448。补位规则是先补一个1后面补0直到满足条件。之所以是448而不是512是因为最后64位要用来记录原始消息的长度这样总长度就是512的整数倍。分块补位完成后的消息按每512比特分成若干个数据块每个块又拆成16个32比特的字。初始化缓冲区MD5使用四个32位寄存器A、B、C、D初始值固定为A 0x67452301B 0xEFCDAB89C 0x98BADCFED 0x10325476 这四个值不是随便定的它们是标准规定的初始化向量任何MD5实现都用同一组。循环压缩每个512比特块执行四轮处理每轮16步操作共64步。每一步使用一个非线性函数F、G、H、I、一个移位量和一张常数表T[i]由正弦函数生成。四轮结束后将结果累加到A、B、C、D上然后处理下一个块。所有块处理完毕把A、B、C、D按小端字节序拼接就得到32位的十六进制摘要。这里有一个很多人不理解的地方为什么MD5输出是32位十六进制字符串因为128位除以4一个十六进制字符4比特等于32个字符。所以判断一个MD5实现对不对最快的方式就是看输出长度和字符集正常结果应该是由0-9和a-f组成的32位小写字符串。2.2 一次完整签名计算示例下面用一个实际场景演示MD5签名的完整计算过程。假设接口需要以下参数参数名参数值cityCode110100goodsId10086timestamp1710000000密钥key为a1b2c3d4。签名规则是参数按字典序排序后拼接末尾追加key。第一步将所有参数名排序。字典序排序后是cityCode、goodsId、timestamp因为c g t。第二步拼接字符串cityCode110100goodsId10086timestamp1710000000a1b2c3d4注意这里不是每个键值对末尾都加而是像URL query string一样用连接键值对最后一个键值对后面直接跟密钥不再加任何分隔符。这是最常见的签名拼接方式。第三步对这个字符串计算MD5。用Python验证import hashlib str_to_sign cityCode110100goodsId10086timestamp1710000000a1b2c3d4 md5_result hashlib.md5(str_to_sign.encode(utf-8)).hexdigest() print(md5_result)运行结果会输出一个32位小写十六进制字符串这就是sign参数。这里有一个关键细节对字符串编码时必须指定UTF-8因为MD5处理的是字节流同一个字符串用不同编码会得到完全不同的结果。很多签名对不上的问题根源就在编码不一致——客户端用GBK服务端用UTF-8两边长度和字节内容不同签名自然不同。2.3 服务端验签为什么也用MD5有些人会问MD5不是已经能被碰撞攻击了吗为什么签名还在用它这里要区分两个概念密码存储和签名校验。密码存储场景下攻击者拿到MD5值之后可以做彩虹表反查所以现在正规系统都用bcrypt、scrypt这类加盐慢哈希。但接口签名场景不一样签名串里本身包含了时间戳、随机数、密钥每次请求的签名串都不同攻击者即使截获了一组请求的签名也无法重放到另一个请求上因为参数变了。而且服务端验签追求的是“计算快”MD5的计算速度很快在高并发接口下性能优势明显。当然MD5签名也有需要注意的地方。如果签名规则设计得过于简单比如直接把固定字符串加固定密钥拼接那么攻击者可以通过大量样本去推测密钥。这也是为什么很多团队会在MD5基础上叠加“加盐”“倒序”“二次加密”等手段。但从算法层面来说MD5用于接口签名校验只要密钥不泄露、签名串包含时间戳等动态参数安全性是够用的。3. 城市编码为空深度排查思路3.1 先分清报错来自网关还是业务排查“城市编码不能为空”第一步不是改代码而是看报错字段。如果返回体里同时有sign相关的错误码比如sign_invalid、sign_expired那说明签名校验环节就挂了如果签名校验过了单独提示cityCode cannot be empty那就要去查业务参数。我习惯的做法是先用接口调试工具直接构造一个最简单的请求把cityCode手动填上其他参数按文档要求补齐看能不能调通。如果能通说明服务端本身没问题问题在客户端构造请求的链路如果手动构造也报错那要么是文档里的签名规则写错了要么是自己理解有偏差。3.2 五个典型触发场景根据我在实际项目中踩过的坑cityCode为空通常有五种情况客户端没有采集到定位信息。App启动时如果用户没给定位权限或者定位SDK还没回调此时获取到的cityCode就是空字符串。有些团队会在定位成功前禁止发请求有些则会用默认城市兜底如果既没有兜底也没有拦截空值就传上去了。参数名不一致。接口文档写的是cityCode客户端代码里写成了cityId或areaCode签名时倒是参与计算了但服务端从请求体里取cityCode时取不到只能拿到空。这类问题在前后端并行开发时特别常见接口文档更新了但客户端没同步。签名时和请求体里值不一致。比如签名时城市编码取的是定位结果110100但请求体里的cityCode被后续逻辑置空了或者反过来。服务端验签用请求体里的空值签名必定不匹配。空值参数被排除在签名外。有些签名规则写的是“排除空值参数后再签名”如果客户端判断cityCode为空就把它从签名串里剔除了但服务端要求这个字段必填签完名才发现业务参数缺失。网关层统一赋值失败。这种情况更隐蔽。有的系统中cityCode不在客户端传而是由网关根据用户会话或IP统一注入。如果网关没有拿到用户归属地或者IP解析服务超时这个字段就不会被注入服务端拿到的自然是空。前三种跟签名和参数传递直接相关最后一种更像环境问题。排查的时候建议按数据流方向逐步查客户端定位SDK有没有返回值 → 签名构造时用的是哪个变量 → 请求体最终序列化后长什么样 → 服务端日志里收到的原始报文是什么。3.3 抓包排查的完整过程排查这类问题最有效的手段是抓包。手机端可以用Charles或FiddlerPC端直接用Chrome DevTools的Network面板。下面是我在真实项目中的操作流程打开抓包工具设置代理并安装证书确保能看到HTTPS明文流量。在App里触发一个需要城市编码的接口请求。找到对应的请求观察请求URL和请求体。重点看两个地方请求体里有没有cityCode字段值是什么请求体里是否存在sign以外的其他参数与文档不一致。如果请求体里直接没有cityCode问题在客户端参数构造层去查定位SDK回调或参数赋值逻辑。如果请求体里有cityCode但服务端仍然报空那就是服务端解析的问题要么是服务端读取的字段名不对要么是网关层把值覆盖成了空。复制抓到的请求参数在本地用脚本重算签名与服务端的验签逻辑对比确认签名本身是否正确。抓包这一步能省掉大量靠猜的时间。签名问题最忌讳的就是改一行代码试一次频繁试错不仅效率低还可能把缓存、会话这类因素卷进来干扰判断。4. 完整复现与修复实操4.1 用Python还原MD5签名先给出一个完整的签名生成函数这是后续一切调试的基础import hashlib import time from urllib.parse import quote_plus def generate_sign(params: dict, key: str) - str: # 1. 剔除空值和sign本身 filtered { k: str(v) for k, v in params.items() if v not in (None, , null) and k ! sign } # 2. 按字典序排序 sorted_keys sorted(filtered.keys()) # 3. 拼接 keyvalue... raw_str .join(f{k}{filtered[k]} for k in sorted_keys) raw_str_with_key raw_str key # 4. 计算MD5 return hashlib.md5(raw_str_with_key.encode(utf-8)).hexdigest()这段代码里有一个细节字典序排序用的是Python字符串默认排序cityCode、goodsId、timestamp这个顺序是稳定的。但如果你在别的语言里实现要注意排序规则是否一致尤其是大小写字母混合的情况数字、大写字母、小写字母在ASCII码中的排列顺序是0-9 A-Z a-z不同语言的默认排序可能不一样最终拼出来的字符串就会不同。4.2 构造带城市编码的完整请求有了签名函数接下来可以构造一个完整的测试请求import requests def build_request(city_code: str, goods_id: str, key: str): timestamp int(time.time()) params { cityCode: city_code, goodsId: goods_id, timestamp: timestamp, } sign generate_sign(params, key) params[sign] sign return params # 测试正常城市编码 params build_request(110100, 10086, a1b2c3d4) resp requests.post(https://api.example.com/goods/detail, dataparams, timeout5) print(resp.status_code, resp.text) # 测试城市编码为空 params build_request(, 10086, a1b2c3d4) resp requests.post(https://api.example.com/goods/detail, dataparams, timeout5) print(resp.status_code, resp.text)跑第一个请求时理论上应该返回正常的业务数据跑第二个请求时大概率能复现“城市编码不能为空”的报错。这里就出现了一个值得思考的问题空字符串在签名函数里被当作空值剔除了也就是说这次请求的签名串里没有cityCode。服务端如果也是按“剔除空值后验签”的规则签名能通过但业务校验会失败。这就解释了为什么会出现“签名正确但业务报错”的现象。4.3 兜底方案与修复落地定位到原因之后修复方式通常有两种一种是客户端在参数构造前就从定位SDK获取城市编码取不到就用默认值兜底另一种是服务端在网关层做注入。我在实践中倾向于客户端兜底与服务端兜底同时做双保险。客户端兜底的实现逻辑大概是def get_city_code(): location_info get_location_from_sdk() if location_info and location_info.get(cityCode): return location_info[cityCode] # 兜底1: 用上一次缓存的定位结果 cached cache.get(last_city_code) if cached: return cached # 兜底2: 用IP归属地接口 city_code fetch_city_code_by_ip() if city_code: cache.set(last_city_code, city_code, expires3600) return city_code # 兜底3: 默认城市编码 return app_config.get(default_city_code, 110100)这里的关键是兜底顺序合理定位SDK最精准其次是缓存再次是IP归属地最后才是写死的默认城市。如果一上来就用默认城市那么IP在其他城市的用户拿到的内容就错了如果只用定位SDK在模拟器或无权限环境下城市编码就会长时间为空。按这个顺序做既能保证“不为空”又能尽量保证“准确”。服务端网关的兜底则是在检测到cityCode为空时根据用户会话里的历史城市或IP库做注入。客户端兜底能覆盖正常用户的绝大多数场景服务端兜底负责兜住极端情况。5. 常见问题排查速查表与避坑心得5.1 问题速查表把这段时间遇到的相关问题整理成一张表方便遇到同类报错时直接对号入座报错信息可能原因解决方案城市编码不能为空客户端未传或传了空字符串检查定位SDK回调、增加兜底逻辑城市编码不能为空参数名不一致服务端取不到值统一字段名以接口文档为准sign不匹配签名串里包含了空值cityCode但请求体没有统一剔除规则签名串与请求体参数保持一致sign不匹配客户端与服务端MD5编码不一致统一使用UTF-8编码sign不匹配排序规则不一致统一字典序规则按ASCII码排sign不匹配拼接时格式错误比如末尾多加了核对拼接模板最后一个键值对直接跟key请求超时或鉴权失败时间戳与服务端相差过大检查设备时间、时区设置城市编码正确但内容不对网关层按IP覆盖了传值检查网关路由规则这张表背后有一个统一的原则签名这种东西两端必须使用完全相同的规则任何一个细节不一致结果都是灾难性的。所以遇到这类问题第一步永远是“把两边的签名串和签名结果都打出来逐字符对比”。5.2 打印签名串是最快的排查手段我在实际排错时有个习惯客户端在发送请求前把所有要传的参数、排序后的签名串、计算出的MD5值全部打印到日志里服务端同样在验签前打印收到的参数、重算的签名串和MD5值。两边日志一对问题立刻水落石出。有一次排查某接口的签名问题客户端和服务端两边日志都打印了发现拼接串完全一样但MD5结果不一样。后来仔细一看一个是用\r\n换行拼接的一个是用\n拼接的肉眼根本看不出来只有打印出来才能发现这个差别。还有一次是URL编码的问题某个参数值是https://example.com?a1b2客户端把它直接拼进了签名串服务端拿到的却是URL解码后的值因为传输的时候被解析成了参数分隔符。这种坑文档里不会写只能靠日志对比才能定位。5.3 MD5签名相关的几个避坑心得最后分享几个我在实际项目中积累的经验密钥不要硬编码在客户端代码里。虽然客户端逆向是防不住的但至少可以用混淆、加壳增加破解成本。正规做法是把密钥下发到学习终端的安全存储区而不是直接写在Java/Kotlin/Swift源码里。签名串统一用UTF-8编码。这个前面提过但值得再强调一遍。很多老项目的服务端默认GBK如果数据库和接口没有统一编码极容易在中文参数上栽跟头。MD5结果统一转小写。MD5的十六进制输出可以是大写也可以是小写两端必须约定一致。推荐统一转小写因为小写字符串在不同的安全比较函数里行为更稳定。时间戳要参与签名。没有时间戳的签名串是静态的攻击者抓包后可以无限重放。加上时间戳后服务端还应该校验时间窗口超出比如5分钟的请求直接拒绝。空值参数的处理规则要明确。是“空值参数不参与签名”还是“空值参数也要带占位符参与签名”必须在接口文档里写清楚。这两个规则会导致完全不同的签名结果也是“城市编码为空”最容易并发出现签名错误的原因。用哈希比较时要用定长比较函数。不要用直接比较两个MD5字符串用hmac.compare_digest或类似的定长比较函数避免计时攻击。关于MD5的安全级别网上争议很多。我的观点是在接口签名场景MD5仍然可用但前提是配合动态参数和密钥使用。如果对安全性要求更高可以用HMAC-MD5或者HMAC-SHA256代替纯MD5。HMAC本质上是带密钥的哈希运算它把密钥混入哈希过程比“MD5(字符串key)”更抗长度扩展攻击。从实现角度只是把hashlib.md5(datakey)换成hmac.new(key, data, hashlib.md5).hexdigest()改动成本很低效果却好很多。回到最初那个“城市编码不能为空”的报错。如果日志显示签名串里根本没有cityCode那就说明是空值过滤规则把城市编码丢掉了修复方向是调整空值判断逻辑如果日志显示签名串里有cityCode但请求体里没有那就说明是参数传递链路出了问题修复方向是追踪参数从构造到序列化之间被谁赋了空值如果日志显示两端签名结果一致只有业务校验报错那就是网关注入或服务端取参的问题。有一次我在终端设备上排查这个问题发现是产品的权限弹窗把定位权限挡住之后SDK的callback迟迟不回调导致城市编码一直是初始化值。后来在处理逻辑里加了一个超时保护定位超过3秒没返回就触发IP兜底。这个策略上线后“城市编码不能为空”的报错率直接降到了原来的十分之一。所以遇到这类问题不要只盯着签名算法本身数据链路里每个环节都值得检查一遍。