全局开发规范(开发者视角 · 交付用户使用) 0. 文档定位 项目 内容 写文档的人 开发者(你) 用产品的人 终端用户(别人) 核心矛盾 开发者需要功能完整,用户只需要安全可用的产品 解决思路 开发期全功能,交付期最小暴露,运行时动态隔离 默认时区 Asia/Shanghai(UTC+8) 最重要的一句话: 你是开发者,你在开发阶段可以拥有全部功能、全部权限、全部调试能力。但产品交付给用户时,用户只能看到“用户该看到的”,其余全部隐藏、禁用、剥离、混淆、服务端化。开发期的能力 ≠ 交付期的暴露面。 --- 1. 双视角模型 1.1 开发者视角(你) · 拥有源码、密钥、内部接口、调试工具 · 可以访问管理后台、测试账号、Mock 数据 · 可以在本地、测试环境自由操作 · 关注:功能完整、开发效率、可维护性 1.2 用户视角(别人) · 只看到 App / Web / 客户端界面 · 只能调用公开 API 和少量鉴权接口 · 不应该看到任何内部实现、调试入口、开发者信息 · 关注:能用、好用、安全、不泄露隐私 1.3 攻击者视角(潜在威胁) · 会解包、反编译、抓包、读注释、找密钥 · 会尝试打开隐藏页面、调用未公开接口 · 会利用开发者遗留的调试入口、测试账号、后门 · 关注:找漏洞、找密钥、找内部接口、找逻辑缺陷 1.4 三者关系 ```text 开发者(全量能力) ↓ 编译 / 构建 / 部署 服务端(受控暴露) ↓ 鉴权 / 风控 / 加密 用户端(最小暴露) ↑ 攻击者从这里入手 ``` --- 2. 核心原则 2.1 开发期 vs 交付期分离 能力 开发期 交付期 调试菜单 可用 隐藏 / 移除 测试账号 可用 禁用 / 删除 Mock 数据 可用 关闭 内部接口 可调 服务端拒绝 日志详细输出 开启 关闭 / 脱敏 源码映射 保留 剥离 调试符号 保留 剥离 后门入口 临时 禁止 2.2 功能可以在客户端,但不能被用户触发 有些功能必须在客户端实现,但不能以任何方式暴露给用户: · 内部工具页 · 调试面板 · 日志查看器 · 网络抓包入口 · 数据库查看器 · 环境切换 · 账号切换 · 接口 Mock 开关 · 强制更新开关 · 风控绕过开关 处理方式: 1. 编译期排除:用 BuildConfig / 宏 / 编译开关彻底不编入 release。 2. 运行时隐藏:入口不显示,但代码在;需配合加固与混淆。 3. 服务端禁用:客户端能调,服务端直接拒绝。 4. 权限校验:仅内部账号 + 内部设备 + 内部网络可触发。 5. 动态下发:功能开关由服务端控制,默认关闭。 优先顺序:编译期排除 > 服务端禁用 > 运行时隐藏。 只做“运行时隐藏”而不做服务端禁用,等于没防。 2.3 信息最小暴露 · 只暴露必须暴露的 · 能后端做的,不放前端 · 能模糊的,不精确 · 能不说的,不说 2.4 时间默认 UTC+8 · 全项目默认 Asia/Shanghai · API、日志、定时任务、展示统一 · 国际化场景存 UTC,展示转 UTC+8 2.5 客户端不可信 · 任何客户端密钥都可能被逆向 · 任何客户端校验都可能被绕过 · 服务端才是最终防线 · 客户端安全检测只作为风控信号 --- 3. 客户端功能暴露分级 3.1 分级定义 级别 名称 说明 示例 L0 公开功能 所有用户可用 首页、搜索、设置 L1 登录功能 登录后可用 订单、资料、消息 L2 敏感功能 需二次验证 支付、改密、绑卡 L3 内部功能 仅开发者可用 调试、Mock、日志 L4 危险功能 绝不交付 后门、绕过、密钥导出 3.2 各级别处理方式 级别 客户端 服务端 交付 L0 正常显示 公开接口 保留 L1 正常显示 鉴权接口 保留 L2 正常显示 + 二次验证 强鉴权 + 风控 保留 L3 编译期排除 / 隐藏 内部接口拒绝外部 不交付 L4 绝不编入 不存在 不存在 3.3 L3 内部功能的处理 必须在客户端存在但不能被用户触发的功能: · 内部调试菜单 · 环境切换 · 日志上传 · 网络诊断 · 数据库查看 · Mock 开关 · 强制更新 · 缓存清理 · 账号切换 处理方式(按优先级): 1. 编译期排除 ```kotlin if (BuildConfig.DEBUG) { // 仅 debug 包编入 } ``` Release 包中这段代码根本不编译。 2. 服务端禁用 ```text POST /internal/debug/enable → 服务端校验:仅内部账号 + 内部设备 + 内部 IP → 否则 403 ``` 3. 运行时隐藏 · 入口不显示 · 需特定手势 / 密码 / 设备才能触发 · 配合加固,防止逆向找到入口 4. 动态下发 · 功能开关由服务端控制 · 默认关闭 · 仅内部账号开启 只做运行时隐藏是危险的,因为逆向者可以找到入口。必须配合编译期排除或服务端禁用。 --- 4. 文件与信息暴露边界 4.1 必须交付给用户的 类型 说明 客户端安装包 App、桌面端 静态资源 图片、字体、样式 公开配置 API 域名、版本号 用户协议、隐私政策 合规 公开 API 文档 仅公开接口 错误提示 友好、模糊 4.2 绝不交付给用户的 类型 原因 服务端源码 核心逻辑 数据库结构 表、字段、索引 配置文件 连接串、密钥 密钥 设备、会话、服务端 内部 API 仅内部调用 日志文件 含敏感数据 CI/CD 脚本 构建、部署流程 内部文档 架构、设计 开发者信息 姓名、邮箱、账号 调试信息 Debug、Mock、后门 第三方密钥 地图、支付、推送 服务器信息 IP、域名、端口 错误堆栈 完整堆栈、行号 Source Map 源码结构 调试符号 PDB、dSYM .git 目录 完整历史 .env 文件 环境配置 测试代码 内部逻辑 测试账号 安全隐患 4.3 只允许内部保留的 类型 存放 设计文档 内部知识库 架构图 内部知识库 密钥 KMS / HSM 部署脚本 内部私有仓库 运维手册 内部知识库 故障复盘 内部知识库 用户数据 合规存储 4.4 代码注释规范 禁止出现在注释中: · 开发者姓名、邮箱、电话、社交账号 · 内部系统地址、IP、域名 · 账号、密码、Token、密钥 · 数据库表名、字段名、SQL · 内部接口路径、参数 · 安全漏洞说明 · TODO 中暴露未修复问题 · 调试后门、测试账号 · 公司内部术语、项目代号 · 版本历史中的个人贡献者 允许的注释: · 解释“为什么” · 复杂算法思路 · 边界条件 · 外部依赖原因 · 许可证声明 示例: ❌ 错误: ```java // 张三 2024-01-01 添加,用于绕过支付校验,测试账号 admin/123456 // 数据库表 t_user 字段 password // 内部接口 /internal/order/query ``` ✅ 正确: ```java // 根据业务规则,订单状态需在支付完成后异步更新 // 此处使用幂等处理,避免重复消费 ``` 4.5 日志规范 禁止记录: · 用户密码、Token、密钥 · 完整银行卡号、身份证号、手机号 · 数据库连接串 · 内部 IP、域名、路径 · 完整堆栈(生产) · 请求体敏感字段 · 开发者个人信息 允许记录: · TraceId、RequestId · 脱敏后用户标识 · 接口耗时、状态码 · 业务事件 · 错误码 格式: ```text 2026-10-07 15:30:00.123 +08:00 [traceId] [level] message ``` 4.6 错误信息规范 对用户: · 统一友好提示 · 不暴露堆栈、SQL、内部路径 · 不区分“用户不存在”和“密码错误” · 验证码错误统一提示 对开发者(内部日志): · 记录错误码、TraceId、上下文 · 不记录敏感数据 · 生产关闭 Debug 堆栈 4.7 API 暴露边界 接口类型 暴露用户 鉴权 加密 签名 公开接口 是 无/弱 HTTPS 可选 非公开接口 是 强 HTTPS + SM4 是 内部接口 否 服务间鉴权 mTLS 是 管理接口 否 强 + IP 白名单 HTTPS 是 调试接口 否 绝不暴露 - - --- 5. 时间与日期规范(UTC+8) 5.1 强制规则 1. 默认业务时区 Asia/Shanghai(UTC+8) 2. API 时间 ISO 8601 带时区:2026-10-07T15:30:00+08:00 3. 日志时间带时区:2026-10-07 15:30:00.123 +08:00 4. 定时任务指定时区:Asia/Shanghai 5. 前端展示默认 UTC+8,用户可切换 6. 数据库国际化存 UTC,展示转 UTC+8;统一 UTC+8 时全链路显式声明 7. 禁止服务器本地时区 8. 禁止秒/毫秒混用 9. 禁止无时区字符串 10. 测试覆盖跨天、跨月、跨年、闰年、时区转换 5.2 各层要求 层 要求 数据库 timestamptz 或统一 UTC+8 后端 统一时间工具类 API ISO 8601 带时区 前端 统一格式化,默认 UTC+8 App 统一格式化,默认 UTC+8 日志 带时区 定时任务 指定时区 测试 覆盖时区边界 --- 6. 安全与鉴权 6.1 接口分级 · 低风险公开:HTTPS + 限流 · 中高风险鉴权:安全检测 + 服务端风控 + 验签 + 防重放 + 敏感字段加密 6.2 算法选型 用途 算法 传输 HTTPS / TLCP 对称加密 SM4-GCM / AES-GCM 摘要 SM3 签名 SM2 / HMAC-SM3 密钥交换 SM2 / ECDH 密钥存储 Keychain / Keystore / KMS / HSM SM3 不是加密算法,不能用来“全程加密”。 6.3 密钥体系 · 设备密钥:Keychain / Keystore,长期 · 会话密钥:短期 30 分钟,可轮换 · 服务端密钥:KMS / HSM · 禁止硬编码,禁止写日志 6.4 防重放 · timestamp + nonce + requestId · 时间窗 60~300 秒 · nonce Redis SETNX 去重 6.5 服务端处理顺序 ```text TLS 终止 → 限流 → 验签 → 防重放 → 解压 → 解密 → 鉴权 → 风控 → 业务 ``` 6.6 防逆向 · 密钥不硬编码 · 会话密钥短期、一次性、可轮换、可吊销 · 设备绑定、用户绑定、签名绑定 · Keychain / Keystore / StrongBox · 混淆、加固、白盒 · 反调试、反 Hook、反 Root、反模拟器、反重打包 · 证书固定、双向 TLS · 完整性校验 · 服务端风控为最终防线 --- 7. 客户端开发规范 7.1 代码组织 · 模块化、组件化 · 状态管理 · 路由 · 网络层封装 7.2 网络层 · 统一错误处理 · 重试、降级 · 超时 · 取消请求 7.3 本地缓存 · 内存 + 磁盘 · 敏感数据加密 · 缓存 key 设计 7.4 时间展示 · 默认 UTC+8 · 用户可切换时区 · 国际化 7.5 内部功能隔离 编译期排除: ```kotlin if (BuildConfig.DEBUG) { // 仅 debug 包编入 } ``` 服务端禁用: ```text POST /internal/debug/enable → 仅内部账号 + 内部设备 + 内部 IP → 否则 403 ``` 运行时隐藏: · 入口不显示 · 特定手势 / 密码 / 设备触发 · 配合加固 动态下发: · 服务端控制开关 · 默认关闭 · 仅内部账号开启 7.6 防逆向 · 密钥不硬编码 · 会话密钥短期 · 设备绑定 · Keychain / Keystore · 混淆、加固、白盒 · 反调试、反 Hook、反 Root、反模拟器 · 证书固定、双向 TLS · 完整性校验 · 服务端风控 --- 8. 后端开发规范 8.1 架构 · 微服务 / 单体 · 网关 / BFF · 服务间通信 · 数据库、缓存、MQ 8.2 编码 · 命名、注释、异常、空值 · 日志、TraceId · 配置管理 · 密钥管理 8.3 API · REST / gRPC · 版本管理 · 幂等、重试、限流 · 错误码 8.4 数据 · 表设计、索引 · 事务、锁 · 分库分表 · 迁移、备份 8.5 内部接口保护 · 仅服务间调用 · mTLS · IP 白名单 · 服务间鉴权 · 绝不暴露到公网 --- 9. 带宽与性能优化 9.1 协议层 · HTTP/2、HTTP/3、QUIC · 连接复用、长连接 · TLS 1.3、会话复用 · BFF 聚合 9.2 压缩层 · gzip / brotli / zstd · 先压缩再加密 · 小报文不压缩 · 防 BREACH 9.3 报文层 · Protobuf / MessagePack / CBOR · 字段裁剪 · 枚举整数化 · 时间戳整数化 9.4 接口层 · 批量接口 /batch · 聚合接口 · GraphQL 按需查询 · 限制批量大小 9.5 数据层 · 游标分页 · 增量同步 · 差量更新 · 按需加载 9.6 交互层 · WebSocket / SSE / Push 替代轮询 · 防抖、合并请求 · 预取、懒加载 9.7 缓存层 · ETag / 304 · CDN · 本地缓存 · Redis 热点缓存 --- 10. 测试规范 · 单元、集成、E2E · 覆盖率 · Mock · 性能、压力、安全 · 时区测试 · 边界测试 · 内部功能不可被用户触发测试 · Release 包不含调试功能测试 --- 11. CI/CD 与运维 · 流水线:lint / test / build / scan / deploy · 制品、镜像、版本 · 容器化、K8s · 蓝绿、灰度、金丝雀 · 回滚、降级 · 监控、告警、日志 构建检查: · Release 包剥离调试符号 · 关闭 Source Map · 移除内部文档 · 移除测试资源 · 移除 .git · 移除 .env · 混淆代码 --- 12. 合规与隐私 · 数据分类分级 · 隐私政策 · 最小必要 · 脱敏、加密、删除、导出 · 审计日志 · 国密合规、密评、等保 --- 13. 检查清单 开发者信息 ☐ 代码无开发者个人信息 ☐ 注释无开发者个人信息 ☐ 提交信息无个人信息 ☐ 构建产物无个人信息 ☐ 文档无个人信息 ☐ 截图无个人信息 信息暴露 ☐ 代码注释无密钥、内部路径 ☐ 日志无敏感数据、堆栈、内部 IP ☐ 错误提示友好、模糊 ☐ API 文档只含公开接口 ☐ 客户端无硬编码密钥 ☐ 配置文件不进入客户端 ☐ 生产环境关闭 Debug 内部功能隔离 ☐ L3 功能编译期排除或服务端禁用 ☐ L4 功能绝不编入 ☐ 调试入口 Release 包不可见 ☐ 测试账号 Release 包不可用 ☐ Mock 开关 Release 包关闭 ☐ 内部接口服务端拒绝外部调用 ☐ 内部接口不暴露公网 ☐ 内部接口有 mTLS / IP 白名单 时间 ☐ 默认 UTC+8 ☐ API 时间带时区 ☐ 日志时间带时区 ☐ 定时任务指定时区 ☐ 测试覆盖时区边界 安全 ☐ 接口分级 ☐ 中高风险接口安全检测 ☐ 服务端风控 ☐ SM4-GCM 加密敏感字段 ☐ SM3/SM2 签名 ☐ 防重放 ☐ 密钥安全存储 ☐ 证书固定、加固、混淆 ☐ 反调试、反 Hook、反 Root 性能 ☐ HTTP/2 或 HTTP/3 ☐ 连接复用 ☐ 压缩在加密之前 ☐ 批量、增量、缓存 ☐ 推送替代轮询 ☐ 防 BREACH --- 14. 最终原则 你写代码时是开发者,产品最终给用户用。开发期你可以拥有全部功能、全部权限、全部调试能力;交付期用户只能看到“用户该看到的”。所有暴露面都要按“使用者”和“攻击者”视角审查。 只暴露必须暴露的。代码、注释、日志、错误信息中不出现开发者信息、内部实现、密钥、敏感数据。 时间默认 UTC+8。 安全上假设客户端不可信,服务端才是最终防线。 性能上先减量、再压缩、再加密、再签名。 防逆向要短期密钥、设备绑定、白盒、加固、证书固定、服务端风控。 内部功能优先编译期排除,其次服务端禁用,最后才是运行时隐藏。只做运行时隐藏等于没防。