团队规范

我列举一些比较重要的问题：

  • 起名字
    • url path名，服务/repo名，代码文件名，包名，不同环境的配置文件名，数据表名…大致统一一下，尤其是分隔符用哪个确定好.
    • 对于业务术语（中文，英文，和用在代码里的名字），最好弄一个大文档记录下来，并同步给所有人。避免同一个意思用不同的名字/术语。
  • 前后端的接口规范，一般是基于http + json或者http + PB的规范。尤其是对客户端的信息传递和response错误的处理。有些人偏爱Restful，但Restful从业务角度非常不完备，即便用Restful也要补充很多信息。具体怎么做我这里不详细列举，但把要关心的问题提出来：
    • 约定用户/后台客服授权token的格式和有效期规范。
    • 约定客户端的类型和版本号。类型是指如iOS App，Android App，微信Web，微信公众号，微信小程序，PC Web，iOS Web， Android Web等不同的类型，便于后端有针对性地返回结果。还有可能候选需要根据前端的屏幕尺寸，解析度返回不同格式的资源。版本号一般用一个buildNo来代表，用来支持Feature Gating。
    • 如何表达授权失败，让前端弹出登陆界面
    • 如何表达业务错误，以及发生这个错误后前端应该展示文案的规则
    • 如何表达网络超时等系统级错误，以及这个错误发生后是否要自动重试，还是让用户手工重试
    • 如何表达一个东西“没有”，比如用户信息里没有设置手机号，这个到底是用“”表示还是用null表示等
    • 如果后端返回的请求体是html而不是json或者PB，前端的行为应该是？
    • 常用数据类型的接口规范，如金额到底用decimal还是用分为单位的整数；日期和时间是用timestamp还是用ISO 8601；时区怎么确定，用+08还是UTC（这个约定要连同数据库配置一起统一）；百分比怎么表示；超过js整数最大值的大整数怎么表示，用新版本js支持的大整数还是用字符串表示。
    • 如果有浮点数前端显示为“最多n位小数“，这个rounding是前端做还是后端做。一般建议后端尽量返回准确的值（哪怕小数会很长）；如果是后端做rounding，也就意味着前端如果对数字做2次计算这类的逻辑时会不准。
    • Native URL的运作方式，即后端返回一个url让前端展示。前端到时是在App里跳转，还是App里面用WebView跳转，还是弹出手机浏览器进行跳转？跳转时的文案怎么处理？
    • Feature Gating的机制，确定某个功能可以在某些特定用户/特定版本的前端上开启/关闭
    • 如果真的有万不得已不能用utf8的场景，要大声吼出来大家一起适配。
  • 打点
    • 业务打点。如前端的界面访问打点。后端下单打点等。便于做ABtest和商业决策分析。
    • 后端系统打点。如api吞吐，延迟，返回成功/错误的计数，CPU/Mem/带宽占用/磁盘占用量等。设置好报警。别主库满了之后才去处理。
  • 域名和CDN
    • 下发域名的规范，即后端可以告诉前端应该用哪个域名访问后端。万一多机房里单机房挂掉，或者域名解析被封禁，还有办法用备用域名访问。
    • 定一个探针机制，让前端可以发现后端设置的下发域名变了，立刻使用新域名配置。这是因为尽管可以改CDN回源或者DNS解析，但扩散速度不够快。
    • 域名的https证书到期之前设个提醒
    • 域名购买的期限到期之前设个提醒。如果自己主域名被竞争对手买走了就自裁谢罪吧。
  • 前端的打包
    • 前端打包时，打开发包，testflight包，线上包的规范。不同的包最好能够同时共存在一个手机上，便于调试。最好将不同类型的包的界面/图标基本颜色搞成不同的，便于识别。
  • 运营
    • 如果后端因为某个原因停服，要求前端挂一个黄条显示文字+链接，或者直接显示“升级中请稍后”，接口和运营规范是什么；
    • 如果前端App出现恶性bug，后端要求封禁和强制升级这个版本的App，要提示用户升级以及升级到什么版本，去哪里下载。
    • 尽早确定一个后台的系统和UI，把整个系统的所有管理/开关工作都集中在这里。Feature Gating的管理也可以做这里。
    • 如果用了云服务，留意下服务费用过低时发出报警。不要搞得都没钱了，云厂商直接停服这种事。如果费用支付还需要几个合伙人+财务的审批才能付出去，就更要留意了。
  • 技术
    • 原则是干一件事只能用一种技术，如服务框架，ORM，RPC，RDS存储，KV存储，在线/离线队列，logging，监控，报警，服务发现，负载均衡，WAF，在线离线推送等。技术选型要特别慎重，不能同一样事情，搞出一堆不同的东西，仅仅是因为开发者个人偏好不同。管不住，后期系统维护和改进就不可能了。
    • 强烈不建议初创项目使用微服务，应该用尽量可以水平扩展的单体服务和部署形式。等开发者多了，用户也多了再说。如果一定要用微服务，选择统一的RPC框架，尽早上k8s。
    • 后台的公共配置写哪里，一般是会整个大的专门放配置的git repo放一堆json/yml/properities文件
    • 表示一个请求的requestId规范。一般建议requestId由客户端产生，并包括时间戳和客户端的信息。这样就能辨别重复的请求（部分弱网优化要求客户端对于同一个请求同时发N个，后端网关需要去重）。这个requestId可以用于log查询，和调用链tracing产生。
    • 表示一个设备的id的规范。说明白比如，一个App被卸载重装后的id是否变化，如何变化之类的问题。
    • 加密的密钥怎么管理，一般建议直接装Vault，先凑合用，除非业务上对加密有特殊要求
    • 对于Java约定好如何使用null;对于js约定好如何使用null/undefined; 对于go约定好如何使用零值和指针nil;（其他语言不太熟，不展开，但类似）
    • 对于redis这种kv，把产生该key的服务名，环境，版本都以某种格式写入到key里。这样混部时好管理。
  • 开发流程
    • 用git就约定一下branch的规范，一般用gitlab flow就行
    • CI的规范，一般用jenkins + workflow或者gitlab ci这样的方式就行