云百技术文档

主题

一、编程规约 ​

（一）命名风格 ​

  1. 【强制】所有编程相关的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。
c#
说明：正确的英文拼写和语法可以让阅读者易于理解，避免歧义。注意，纯拼音命名方式更要避免采用。
正例：ali / alibaba / taobao / cainiao/ aliyun/ youku / hangzhou 等国际通用的名称，可视同英文。
反例：DaZhePromotion [打折] / getPingfenByName() [评分] / String fw[福娃] / int 某变量 = 3
  1. 【强制】代码和注释中都要避免使用任何语言的种族歧视性词语。
c#
正例：日本人 / 印度人 / blockList / allowList / secondary
反例：RIBENGUIZI / Asan / blackList / whiteList / slave
  1. 【强制】所有类、接口、方法、属性、委托、枚举、选项、筛选器等 Public 类型应采用大骆驼式命名法（Camel-Case）命名方式，但以下情形例外：DO / BO / DTO / VO / AO / PO / UID 等。。
c#
正例：ForceCode / UserDO / HtmlDTO / XmlService / TcpUdpDeal / TaPromotion
反例：forcecode / UserDo / HTMLDto / XMLService / TCPUDPDeal / TAPromotion
  1. 【强制】所有非程序执行文件名均采用全字母小写命名法
c#
正例：appsetting.json
反例：Appsetting.json
  1. 【强制】常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。
c#
正例：MAX_STOCK_COUNT / CACHE_EXPIRED_TIME
反例：MAX_COUNT / EXPIRED_TIME
  1. 【强制】所有临时变量、方法变量应采用小骆驼式命名法（Camel-Case）命名方式。
c#
正例： string sampleValue
反例： string samplevalue
  1. 【强制】私有变量建议以 _ 开头并采用小骆驼式命名法（Camel-Case）命名方式
c#
正例： string _sampleValue

  1. 【强制】抽象类命名使用 Abstract 或 Base 结尾；接口命名使用 I 单词开头；选项类命名使用 Options 结尾；筛选器命名使用 Filter 结尾；帮助类命名使用 Helper 结尾；拓展类命名使用 Extension 结尾；异常类命名使用 Exception 结尾；测试类命名以它要测试的类的名称开始，以 Test 结尾。

  2. 【强制】类型与中括号紧挨相连来表示数组。

c#
正例：定义整形数组 int[] arrayDemo。
反例：在 main 参数中，使用 String args[]来定义。
  1. 【强制】杜绝完全不规范的缩写，避免望文不知义。
c#
反例：AbstractClass“缩写”成 AbsClass；condition“缩写”成 condi；Function 缩写”成 Fu，此类
随意缩写严重降低了代码的可阅读性。
  1. 【推荐】为了达到代码自解释的目标，任何自定义编程元素在命名时，使用尽量完整的单词组合来表达。
c#
正例：对某个对象引用的 volatile 字段进行原子更新的类名为 AtomicReferenceFieldUpdater。
反例：常见的方法内变量为 int a;的定义方式。
  1. 【推荐】在常量与变量的命名时，表示类型的名词放在词尾，以提升辨识度。
c#
正例：startTime / workQueue / nameList / TERMINATED_THREAD_COUNT
反例：startedAt / QueueOfWork / listName / COUNT_TERMINATED_THREAD
  1. 【推荐】如果模块、接口、类、方法使用了设计模式，在命名时需体现出具体模式。
c#
说明：将设计模式体现在名字中，有利于阅读者快速理解架构设计理念。
正例： public class OrderFactory;
 public class LoginProxy;
 public class ResourceObserver;
  1. 【参考】枚举类名带上 Enum 后缀，枚举成员名称应采用大骆驼式命名法（Camel-Case）。
c#
说明：枚举其实就是特殊的常量类，且构造方法被默认强制是私有。
正例：枚举名字为 ProcessStatusEnum 的成员名称：SUCCESS / UNKNOWN_REASON。
  1. 【参考】各层命名规约：
c#
A Service/DAO 层方法命名规约
1） 获取单个对象的方法用 get 做前缀。
2） 获取多个对象的方法用 list 做前缀，复数结尾，如：listObjects。
3） 获取统计值的方法用 count 做前缀。
4） 插入的方法用 save/insert 做前缀。
5） 删除的方法用 remove/delete 做前缀。
6） 修改的方法用 update 做前缀。
    
B 领域模型命名规约
1） 数据对象：xxxDO，xxx 即为数据表名。
2） 数据传输对象：xxxDTO，xxx 为业务领域相关的名称。
3） 展示对象：xxxVO，xxx 一般为网页名称。
4） POJO 是 DO/DTO/BO/VO 的统称，禁止命名成 xxxPOJO。

（二）常量定义 ​

  1. 【强制】不允许任何魔法值（即未经预先定义的常量）直接出现在代码中。
c#
反例：
// 本例中，开发者 A 定义了缓存的 key，然后开发者 B 使用缓存时少了下划线，即 key 是"Id#taobao"+tradeId，导致出现故障
String key = "Id#taobao_" + tradeId;
cache.put(key, value);
  1. 【强制】在 long 或者 Long 赋值时，数值后使用大写字母 L，不能是小写字母 l，小写容易跟 数字混淆，造成误解。
c#
说明：Long a = 2l; 写的是数字的 21，还是 Long 型的 2？
  1. 【推荐】不要使用一个常量类维护所有常量，要按常量功能进行归类，分开维护。
c#
说明：大而全的常量类，杂乱无章，使用查找功能才能定位到修改的常量，不利于理解，也不利于维护。
正例：缓存相关常量放在类 CacheConsts 下；系统配置相关常量放在类 SystemConfigConsts 下。
  1. 【推荐】如果变量值仅在一个固定范围内变化用 enum 类型来定义。
c#
正例：
public enum SeasonEnum {
    SPRING = 1, SUMMER = 2, AUTUMN = 3, WINTER = 4
}

（三）代码格式 ​

  1. 【强制】如果是大括号内为空，则简洁地写成{}即可，大括号中间无需换行和空格；如果是非空代码块则： 使用开发工具进行格式化，保持默认风格
c#
1） 左大括号前不换行。
2） 左大括号后换行。
3） 右大括号前换行。
4） 右大括号后还有 else 等代码则不换行；表示终止的右大括号后必须换行。
  1. 【强制】左小括号和右边相邻字符之间不出现空格；右小括号和左边相邻字符之间也不出现空格；而左大括号前需要加空格。详见第 5 条下方正例提示。
c#
反例：if (空格 a == b 空格)

  1. 【强制】if/for/while/switch/do 等保留字与括号之间都必须加空格。

  2. 【强制】任何二目、三目运算符的左右两边都需要加一个空格。

c#
说明：包括赋值运算符=、逻辑运算符&&、加减乘除符号等。

  1. 【强制】采用 4 个空格缩进，禁止使用 Tab 字符。

  2. 【强制】注释的双斜线与注释内容之间有且仅有一个空格。

c#
正例：
    // 这是示例注释，请注意在双斜线之后有一个空格
    int commentInt = new ();
  1. 【强制】在进行类型强制转换时，右括号与强制转换值之间不需要任何空格隔开。
c#
正例：
    double first = 3.2d;
    int second = (int)first + 2;
  1. 【强制】单行字符数限制不超过 120 个，超出需要换行，换行时遵循如下原则：
c#
1）第二行相对第一行缩进 4 个空格，从第三行开始，不再继续缩进，参考示例。
2）运算符与下文一起换行。
3）方法调用的点符号与下文一起换行。
4）方法调用中的多个参数需要换行时，在逗号后进行。
5）在括号前不要换行，见反例。

正例：
StringBuilder sb = new StringBuilder();
// 超过 120 个字符的情况下，换行缩进 4 个空格，并且方法前的点号一起换行
sb.Append("yang").Append("hao")...
    .Append("chen")...
    .Append("chen")...
    .Append("chen");

反例：
StringBuilder sb = new StringBuilder();
// 超过 120 个字符的情况下，不要在括号前换行
sb.Append("you").Append("are")...Append
    ("lucky");
// 参数很多的方法调用可能超过 120 个字符，逗号后才是换行处
Method(args1, args2, args3, ...
       , argsX);
  1. 【强制】方法参数在定义和传入时，多个参数逗号后面必须加空格。
c#
正例：下例中实参的 args1，后边必须要有一个空格。
Method(args1, args2, args3);
  1. 【推荐】单个方法的总行数不超过 80 行。
c#
说明：除注释之外的方法签名、左右大括号、方法内代码、空行、回车及任何不可见字符的总行数不超过80 行。
正例：代码逻辑分清红花和绿叶，个性和共性，绿叶逻辑单独出来成为额外方法，使主干代码更加清晰；共性逻辑抽取成为共性方法，便于复用和维护。
  1. 【推荐】没有必要增加若干空格来使变量的赋值等号与上一行对应位置的等号对齐。
c#
正例：
    int one = 1;
    long two = 2L;
    float three = 3F;
    StringBuilder sb = new StringBuilder();
说明：增加 sb 这个变量，如果需要对齐，则给 one、two、three 都要增加几个空格，在变量比较多的情况下，是非常累赘的事情。
  1. 【推荐】不同逻辑、不同语义、不同业务的代码之间插入一个空行分隔开来以提升可读性。
c#
说明：任何情形，没有必要插入多个空行进行隔开。

（四）控制语句 ​

  1. 【强制】在一个 switch 块内，每个 case 要么通过 continue/break/return 等来终止，要么 注释说明程序将继续执行到哪一个 case 为止；在一个 switch 块内，都必须包含一个 default 语句并且放在最后，即使它什么代码也没有。
c#
说明：注意 break 是退出 switch 语句块，而 return 是退出方法体。
  1. 【强制】在 if/else/for/while/do 语句中必须使用大括号。
c#
说明：即使只有一行代码，也禁止不采用大括号的编码方式：if (condition) statements;
  1. 【强制】在高并发场景中，避免使用”等于”判断作为中断或退出的条件。
c#
说明：如果并发控制没有处理好，容易产生等值判断被“击穿”的情况，使用大于或小于的区间判断条件
来代替。

反例：判断剩余奖品数量等于 0 时，终止发放奖品，但因为并发处理错误导致奖品数量瞬间变成了负数，
这样的话，活动无法终止。
  1. 【推荐】当某个方法的代码总行数超过 10 行时，return / throw 等中断逻辑的右大括号后均需要加一个空行。
c#
说明：这样做逻辑清晰，有利于代码阅读时重点关注。

  1. 【推荐】循环体中的语句要考量性能，以下操作尽量移至循环体外处理，如定义对象、变量、 获取数据库连接，进行不必要的 try-catch 操作（这个 try-catch 是否可以移至循环体外）。

  2. 【推荐】避免采用取反逻辑运算符。

c#
说明：取反逻辑不利于快速理解，并且取反逻辑写法一般都存在对应的正向逻辑写法。
正例：使用 if (x < 628) 来表达 x 小于 628。
反例：使用 if (!(x >= 628)) 来表达 x 小于 628。
  1. 【推荐】公开接口需要进行入参保护，尤其是批量操作的接口。
c#
反例：某业务系统，提供一个用户批量查询的接口，API 文档上有说最多查多少个，但接口实现上没做任何保护，导致调用方传了一个 1000 的用户 id 数组过来后，查询信息后，内存爆了。
  1. 【参考】下列情形，需要进行参数校验：
c#
调用频次低的方法。
执行时间开销很大的方法。此情形中，参数校验时间几乎可以忽略不计，但如果因为参数错误导致中间执行回退，或者错误，那得不偿失。
需要极高稳定性和可用性的方法。
对外提供的开放接口，不管是 RPC/API/HTTP 接口。
敏感权限入口。
  1. 【参考】下列情形，不需要进行参数校验：
c#
极有可能被循环调用的方法。但在方法说明里必须注明外部参数检查。
底层调用频度比较高的方法。毕竟是像纯净水过滤的最后一道，参数错误不太可能到底层才会暴露问题。一般 DAO 层与 Service 层都在同一个应用中，部署在同一台服务器中，所以 DAO 的参数校验，可以省略。
被声明成 private 只会被自己代码所调用的方法，如果能够确定调用方法的代码传入参数已经做过检查或者肯定不会有问题，此时可以不校验参数。

（五）注释规约 ​

  1. 【强制】类、类属性、类方法的注释必须使用规范，使用

    ///

    /// 内容 /// 格式，不得使用 // xxx 方式。

  2. 【强制】所有的抽象方法（包括接口中的方法）必须要用注释、除了返回值、参数、 异常说明外，还必须指出该方法做什么事情，实现什么功能。

c#
说明：对子类的实现要求，或者调用注意事项，请一并说明。

  1. 【强制】方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/* */注释，注意与代码对齐。

  2. 【强制】所有的枚举类型字段必须要有注释，说明每个数据项的用途。

  3. 【推荐】与其“半吊子”英文来注释，不如用中文注释把问题说清楚。专有名词与关键字保持 英文原文即可。

c#
反例：“TCP 连接超时”解释成“传输控制协议连接超时”，理解反而费脑筋。
  1. 【推荐】代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改。
c#
说明：代码与注释更新不同步，就像路网与导航软件更新不同步一样，如果导航软件严重滞后，就失去了导航的意义。

  1. 【推荐】在类中删除未使用的任何字段、方法、内部类；在方法中删除未使用的任何参数声明与内部变量。

  2. 【参考】谨慎注释掉代码。在上方详细说明，而不是简单地注释掉。如果无用，则删除。

c#
说明：代码被注释掉有两种可能性：1）后续会恢复此段代码逻辑。2）永久不用。前者如果没有备注信息，难以知晓注释动机。后者建议直接删掉即可，假如需要查阅历史代码，登录代码仓库即可。

  1. 【参考】对于注释的要求：第一、能够准确反映设计思想和代码逻辑；第二、能够描述业务含 义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同 天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继任者看 的，使其能够快速接替自己的工作。

  2. 【参考】好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的一个极端：过多过滥的注释，代码的逻辑一旦修改，修改注释又是相当大的负担。

c#
反例：
// put elephant into fridge 
put(elephant, fridge);
方法名 put，加上两个有意义的变量名 elephant 和 fridge，已经说明了这是在干什么，语义清晰的代码不需要额外的注释。
  1. 【参考】特殊注释标记，请注明标记人与标记时间。注意及时处理这些标记，通过标记扫描， 经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。
c#
1) 待办事宜（TODO）:（标记人，标记时间，[预计处理时间]）
	表示需要实现，但目前还未实现的功能。这实际上是一个 c#doc 的标签，目前的 c#doc 还没有实现，但已经被广泛使用。只能应用于类，接口和方法（因为它是一个 c#doc 标签）。
    
2) 错误，不能工作（FIXME）:（标记人，标记时间，[预计处理时间]）
	在注释中用 FIXME 标记某代码是错误的，而且不能工作，需要及时纠正的情况。

（六）前后端规约 ​

  1. 【强制】前后端交互的 API，需要明确协议、域名、路径、请求方法、请求内容、状态码、响应体。
c#
说明：
1） 协议：生产环境必须使用 HTTPS。
2） 路径：每一个 API 需对应一个路径，表示 API 具体的请求地址：
    a） 代表一种资源，只能为名词，推荐使用复数，不能为动词，请求方法已经表达动作意义。
    b） URL 路径不能使用大写，单词如果需要分隔，统一使用下划线。
    c） 路径禁止携带表示请求内容类型的后缀，比如".json",".xml"，通过 accept 头表达即可。
3） 请求方法：对具体操作的定义，常见的请求方法如下：
    a） GET：从服务器取出资源。
    b） POST：在服务器新建一个资源。
    c） PUT：在服务器更新资源。
    d） DELETE：从服务器删除资源。
4） 请求内容：URL 带的参数必须无敏感信息或符合安全要求；body 里带参数时必须设置 Content-Type。
5） 响应体：响应体 body 可放置多种数据类型，由 Content-Type 头来确定。
  1. 【强制】前后端数据列表相关的接口返回，如果为空，则返回空数组[]或空集合{}。
c#
说明：此条约定有利于数据层面上的协作更加高效，减少前端很多琐碎的 null 判断。
  1. 【强制】服务端发生错误时，返回给前端的响应信息必须包含 HTTP 状态码，errorCode、 errorMessage、用户提示信息四个部分。
c#
说明：四个部分的涉众对象分别是浏览器、前端开发、错误排查人员、用户。其中输出给用户的提示信息要求：简短清晰、提示友好，引导用户进行下一步操作或解释错误原因，提示信息可以包括错误原因、上下文环境、推荐操作等。 errorCode：参考附表2。errorMessage：简要描述后端出错原因，便于错误排查人员快速定位问题，注意不要包含敏感数据信息。
    
正例：常见的 HTTP 状态码如下
	200 OK: 表明该请求被成功地完成，所请求的资源发送到客户端。
	401 Unauthorized: 请求要求身份验证，常见对于需要登录而用户未登录的情况。
	403 Forbidden：服务器拒绝请求，常见于机密信息或复制其它登录用户链接访问服务器的情况。
	404 Not Found: 服务器无法取得所请求的网页，请求资源不存在。
	500 Internal Server Error: 服务器内部错误。
  1. 【强制】在前后端交互的 JSON 格式数据中，所有的 key 必须为小写字母开始的 lowerCamelCase 风格，符合英文表达习惯，且表意完整。
c#
正例：errorCode / errorMessage / assetStatus / menuList / orderList / configFlag
反例：ERRORCODE / ERROR_CODE / error_message / error-message / errormessage / ErrorMessage / msg

  1. 【强制】errorMessage 是前后端错误追踪机制的体现，可以在前端输出到 type="hidden" 文字类控件中，或者用户端的日志中，帮助我们快速地定位出问题。

  2. 【强制】对于需要使用超大整数的场景，服务端一律使用 String 字符串类型返回，禁止使用 Long 类型。

c#
说明：服务端如果直接返回 Long 整型数据给前端，JS 会自动转换为 Number 类型（注：此类型为双精度浮点数，表示原理与取值范围等同于 Double）。Long 类型能表示的最大值是 2 的 63 次方-1，在取值范围之内，超过 2 的 53 次方 (9007199254740992)的数值转化为 JS 的 Number 时，有些数值会有精度损失。扩展说明，在 Long 取值范围内，任何 2 的指数次整数都是绝对不会存在精度损失的，所以说精度损失是一个概率问题。若浮点数尾数位与指数位空间不限，则可以精确表示任何整数，但很不幸，双精度浮点数的尾数位只有 52 位。
    
反例：通常在订单号或交易号大于等于 16 位，大概率会出现前后端单据不一致的情况，比如，"orderId": 362909601374617692，前端拿到的值却是: 362909601374617660。
  1. 【强制】HTTP 请求通过 URL 传递参数时，不能超过 2048 字节。
c#
说明：不同浏览器对于 URL 的最大长度限制略有不同，并且对超出最大长度的处理逻辑也有差异，2048 字节是取所有浏览器的最小值。
反例：某业务将退货的商品 id 列表放在 URL 中作为参数传递，当一次退货商品数量过多时，URL 参数超长，传递到后端的参数被截断，导致部分商品未能正确退货。
  1. 【强制】HTTP 请求通过 body 传递内容时，必须控制长度，超出最大长度后，后端解析会出错。
c#
说明：nginx 默认限制是 1MB，tomcat 默认限制为 2MB，当确实有业务需要传较大内容时，可以通过调大服务器端的限制。

  1. 【强制】在翻页场景中，用户输入参数的小于 1，则前端返回第一页参数给后端；后端发现用户输入的参数大于总页数，直接返回最后一页。

  2. 【强制】服务器内部重定向必须使用 forward；外部重定向地址必须使用 URL 统一代理模块 生成，否则会因线上采用 HTTPS 协议而导致浏览器提示“不安全”，并且还会带来 URL 维护不一致的问题。

  3. 【推荐】服务器返回信息必须被标记是否可以缓存，如果缓存，客户端可能会重用之前的请求结果。

c#
说明：缓存有利于减少交互次数，减少交互的平均延迟。
正例：http 1.1 中，s-maxage 告诉服务器进行缓存，时间单位为秒，用法如下：
    response.setHeader("Cache-Control", "s-maxage=" + cacheSeconds);
  1. 【推荐】服务端返回的数据，使用 JSON 格式而非XML。
c#
说明：尽管 HTTP 支持使用不同的输出格式，例如纯文本，JSON，CSV，XML，RSS 甚至 HTML。如果我们使用的面向用户的服务，应该选择 JSON 作为通信中使用的标准数据交换格式，包括请求和响应。此外，application/JSON 是一种通用的 MIME 类型，具有实用、精简、易读的特点。

  1. 【推荐】前后端的时间格式统一为"yyyy-MM-dd HH:mm:ss"，统一为 GMT。

  2. 【参考】在接口路径中不要加入版本号，版本控制在 HTTP 头信息中体现，有利于向前兼容。

c#
说明：当用户在低版本与高版本之间反复切换工作时，会导致迁移复杂度升高，存在数据错乱风险。