1.技术规范

开发规范

1.主流规范

参考阿里、腾讯、谷歌等公司的开发规范。见：E:\1.Java\规范\腾讯技术规范

• 阿里技术规范《码出高效：Java开发手册》
• 腾讯技术规范
  1. 开发语言规范。包括Java、golang、python、c++等。虽然阿里的Java规范最流程，但是与Google的Java规范比较还是不够实用。
  2. 持续集成与持续部署。CI/CD、常用的各类流水线
  3. 代码质量与技术债。
  4. 测试。包括单元测试、集成测试、UI测试。接口自动化测试算是一种特殊的集成测试
  5. Code Review
  6. 重构

2.错误码

参考

• 腾讯云服务器API错误码
• http状态码

• dubbo错误码机制的介绍

• 严格的错误码： 通过错误码统一整个项目的 code 和 message。缺点：文字提示过于笼统
• 中庸之道：强制固定 code、自定义 message

注意事项：异常信息的第一使用者是人，这里包括使用者（用户）和异常处理者（运营人员、程序员）

异常需要进行细分：业务异常和系统 bug

通过aop的方式统一处理异常。

安全开发规范

参考阿里、腾讯、谷歌等公司的开发规范

• 腾讯技术规范E:\1.Java\规范\腾讯技术规范
• 腾讯开源的面向开发人员梳理的代码安全指南https://github.com/Tencent/secguide

重构规范

如何重构

Code Review

Talk Is Cheap, Show Me The Code， 知易行难

架构师，就是掌握大量设计理念和原则、落地到各种语言及附带工具链（生态）下的实践方法、垂直行业模型理解，定制系统模型设计和工程实践规范细则。 进而控制 30+万行代码项目的开发便利性、可维护性、可测试性、运营质量。

腾讯 Code Review 规范

接口设计规范

接口设计规范

• 优秀的 API 接口都是如何设计的
• 如何设计一个良好的接口
• posix标准:https://www.jianshu.com/p/e9e3f17deb36
• oas规范:https://blog.csdn.net/HuaZi_Myth/article/details/104053585
• 深入理解云计算OpenAPI体系:https://mp.weixin.qq.com/s/zsBcikZpkeMzFxvzj1gmaw

OpenAPI标准总结：设计一种标准的、与语言无关的http api接口。

1. 接口设计。选择协议，接口风格。以restfull 接口为例。
   1. 接口风格为 资源导向（使用名称而非动词）
   2. http方法语义（GET/PUT/POST/DELETE）
   3. 统一响应格式，例如使用JSON格式，包括state、msg、data、requestId、error_code等字段信息。
   4. 状态码(非http状态码，而是请求的状态码)，包括定义状态码的错误信息。
2. 版本控制。通常使用路径添加版本号，例如： /api/v1/user
3. 接口文档。开发/测试环境可以暴露出swagger标准的接口文档，提供清晰、明了的接口说明。生产环境关闭。
4. 功能性设计。
   1. 限制请求的数据量。例如分页（限制深度分页查询、限制最大单页条数），请求参数数量（每次提交数量最多100条等）
   2. 幂等性设计：一个请求重复请求，产生同样的影响。例如前端按钮限制，后端分配token、乐观锁等。
   3. 性能优化。缓存（Redis/Memcached）、异步处理（消息队列）、分页 / 批量查询、熔断限流（Hystrix/Sentinel）。做好压力测试。
   4. 设计合理的超时时间和重试次数。
   5. 设计合理的服务降低与熔断机制。避免被上游接口拖死。
      • 超时降级（调用服务时超时返回默认值或者其它处理办法）
      • 失败次数降级（多次调用失败后，服务可用率下降，自动摘除异常节点或者返回默认值等）
      • 限流：也是一种降级
      • 故障降级，也就是熔断机制，主要体现在调用放。例如外部监控系统发生故障进行服务熔断、代理服务（nginx）检测到下游全部异常而返回默认值等。
5. 安全性。
   1. 身份认证和授权。
      • 常见方案：API KEY、jwt、oauth2等。防止未授权用户获取数据；
      • 遵循原则：最小权限原则、敏感信息脱敏/加密等。
      • 重点：防窃取（https）、防篡改(https+签名)、防重放(过期时间)。
   2. 安全机制。使用https、防止sql注入、xss、流量限速（防止暴力破解）、认证有效期（防止请求重放攻击）。

OpenAPI

核心概念

• OpenAPI：狭义上指的是有swagger提出的web api规范。广义上是指对外提供的web api。
• API网关：为webapi提供鉴权、限流、负载均衡、日志、监控等多种功能中间件。
• API工具：方面快速生成webapi文档，方便简单功能开发等功能的工具。

三者直接具备如下关系。

OpenAPI 的作用

是定义 Web API 的标准接口描述和编程语言无关接口描述。 它使人类和计算机可以发现和了解服务的功能，而无需访问源代码、其他文档或检查网络流量。

OpenAPI的发展历史

• OpenAPI最初是在2007年由API工具商Swagger的创始人Tony Tam创造的。如今，OpenAPI是API设计和开发的标准之一，它已成为全球API生态系统中最受欢迎的工具和规范之一。
• OpenAPI最初是为解决API文档和交互的问题设计的，这些方案通常是定制、复杂和难以理解。OpenAPI的主要目标是提供API的统一、易于维护和理解的方式，同时支持多种语言和工具。
• 随着OpenAPI规范的发展，它逐渐被接受为API整个生命周期的标准，包括设计、开发、测试、文档化、部署、管理和监控。
• OpenAPI规范的开放性和可扩展性使其成为了各种API工具和框架的必备标准之一，例如API管理平台、客户端和服务端生成器、测试工具、文档生成器等。
• 于2015 年捐赠给 Linux 基金会后改名为 OpenAPI，并定义最新的规范为 OpenAPI 3.0

厂商的OpenAPI

• 百度：https://cloud.baidu.com/doc/API/index.html
• QQ： https://wiki.connect.qq.com/%E8%AE%BF%E9%97%AEopenAPI%E6%8E%A5%E5%8F%A3
• Tapd：https://www.tapd.cn/help/show#1120003271001000055
• 腾讯云：https://cloud.tencent.com/document/api/213/15730

版本号命名

主流的版本号标准有两个

1. Semver (Semantic Versioning) 语义化版本号， 官网https://semver.org/lang/zh-CN/
2. CalVer (Calendar Versioning) 日历化版本好，官网https://calver.org/overview_zhcn.html

首先看看某些常见软件的版本号：
	Linux Kernel： 0.0.1，1.0.0，2.6.32，3.0.18…，若用 X.Y.Z 表示，则偶数 Y 表示稳定版本，奇数 Y 表示开发版本。
	Windows：windows 98，windows 2000，windows xp，windows 7…，最大的特点是杂乱无章，毫无规律。
	SSH Client：0.9.8。
	OpenStack：2014.1.3，2015.1.1.dev8。
	从上可以看出，不同的软件版本号风格各异，随着系统的规模越大，依赖的软件越多，如果这些软件没有遵循一套规范的命名风格，容易造成 Dependency Hell。
	所以当我们发布版本时，版本号的命名需要遵循某种规则，其中 Semantic Versioning 2.0.0 定义了一套简单的规则及条件来约束版本号的配置和增长。
	本文根据 Semantic Versionning 2.0.0 和 Semantic Versioning 3.0.0 选择性的整理出版本号命名规则指南。

版本号命名规则指南
	版本号的格式为 X.Y.Z(又称 Major.Minor.Patch)，递增的规则为：
	X 表示主版本号，当 API 的兼容性变化时，X 需递增。
	Y 表示次版本号，当增加功能时(不影响 API 的兼容性)，Y 需递增。
	Z 表示修订号，当做 Bug 修复时(不影响 API 的兼容性)，Z 需递增。

详细的规则如下：
	X, Y, Z 必须为非负整数，且不得包含前导零，必须按数值递增，如 1.9.0 -> 1.10.0 -> 1.11.0
	0.Y.Z 的版本号表明软件处于初始开发阶段，意味着 API 可能不稳定；1.0.0 表明版本已有稳定的 API。
	当 API 的兼容性变化时，X 必须递增，Y 和 Z 同时设置为 0；
	当新增功能(不影响 API 的兼容性)或者 API 被标记为 Deprecated 时，Y 必须递增，同时 Z 设置为 0；
	当进行 bug fix 时，Z 必须递增。
	先行版本号(Pre-release)意味该版本不稳定，可能存在兼容性问题，其格式为：X.Y.Z.[a-c][正整数]，如 1.0.0.a1，1.0.0.b99，1.0.0.c1000。
	开发版本号常用于 CI-CD，格式为 X.Y.Z.dev[正整数]，如 1.0.1.dev4。
	版本号的排序规则为依次比较主版本号、次版本号和修订号的数值，如 1.0.0 < 1.0.1 < 1.1.1 < 2.0.0；对于先行版本号和开发版本号，有：1.0.0.a100 < 1.0.0，2.1.0.dev3 < 2.1.0；当存在字母时，以 ASCII 的排序来比较，如 1.0.0.a1 < 1.0.0.b1。
	注意：版本一经发布，不得修改其内容，任何修改必须在新版本发布！

一些修饰的词
	alpha：内部测试版本
	beta：公开测试版本
	gamma：相对成熟的测试版，接近即将发行的正式版
    stable：稳定版（正式版本）
	demo：演示版
	enhance：增强版
	free：自由版
	full version：完整版，即正式版
	lts：长期维护版本
	release：发行版
	rc：即将作为正式版发布
	standard：标准版
	ultimate：旗舰版
	upgrade：升级版
    RTM：生产商发放（Release to Manufacturing）软件产品准备交付，提供给工厂压片的版本，来自于以前还需要使用实体载具（光盘，硬盘等）来进行安装的时代。
    GA：一般可用（General availability）所有必要的商业活动（安全性，合法测试，销售评估等）已经完成，该软件产品已经可以发售的阶段。
    RTW：网络分发（Release to Web，Web发布）利用互联网分发软件
    OEM：计算机厂商随计算机销售的版本，不能零售。
    RTL：零售版（Retail），正式上架的零售版。
	
不同框架中的应用：
1. Maven
    SNAPSHOT：快照版本，如 2.4.0-SNAPSHOT（开发环节）
    RELEASE：正式版本（可以放心使用）
2. Spring
    SNAPSHOT：快照版本，如2020.0.0-SNAPSHOT
    M数字(milestone)：里程碑版本，如2020.0.0-M1、2020.0.0-M2
    RC数字(Release Candidate)：最终产品的候选版本，如果未出现问题则可发布成为正式版本。多数开源软件会推出两个 RC 版本，最后的 RC2 则成为正式版本。如2020.0.0-RC1、2020.0.0-RC2
    无后缀：正式版本，如 2.4.0   

代码分层设计

• MVC
• 分层架构
• COLA

架构模式

公司技术委员会职责

软件开发避免陷入误区

软件研发架构的各种理论方法，其本质都是围绕着"实用"来进行设计的。 所以，事实上不应该有什么软件研发的工作方法是不属于实用主义的，一切的软件架构，软件设计，软件研发管理的方法，都应该是属于实用主义。 但常常，我们在以实用为目的去做事情的时候，很容易受到一些思维误区的干扰，自以为自己是追求实用的，但实际上早已经谬之千里，却不自知。常见的有四大误区。