SonarQube怎么定义新代码 SonarQube新代码周期怎么切换

很多团队在用SonarQube时，真正容易混淆的不是有没有New Code，而是“新代码到底从哪一天开始算”和“项目、分支、全局到底谁说了算”。SonarQube官方把这套逻辑定义得很清楚，New Code可以按Previous version、Number of days、Specific analysis、Reference branch四种方式来定义，而且配置有全局、项目、分支三层覆盖关系，分支级优先于项目级，项目级优先于全局级。

一、SonarQube怎么定义新代码

在SonarQube里定义新代码，关键不是先选一个看起来顺手的周期，而是先按项目交付方式去选基线。官方文档说明，New Code本质上是一个基线设置，它决定哪些代码会被当成“新引入的内容”来参与新代码质量门禁和新代码指标计算，所以这个定义本身会直接影响后面的质量门、缺陷数量和评审节奏。

1、先理解四种新代码定义方式

SonarQube Server当前支持四种新代码定义。Previous version适合有明确版本发布节奏的项目，表示自最近一次版本递增以来变更的代码都算新代码。Number of days适合持续交付场景，表示最近X天内变更的代码算新代码，默认值是30天，最大值是90天。Specific analysis表示从某一次指定分析开始算新代码。Reference branch表示把当前分支和某个参考分支做差异比较，差异部分就是新代码。

2、再按项目节奏选合适口径

如果你的项目是按版本发版、里程碑清晰，通常更适合Previous version。因为官方说明里，这种方式会把新代码周期起点设成当前项目版本第一次分析的时间。要是项目更接近持续交付，没有特别稳定的发版节点，那Number of days或Specific analysis会更灵活。若你主要做分支开发，希望新代码就是相对主干或某个稳定分支的差异，则更适合Reference branch。

3、Previous version不是只改UI就够

很多人以为选了Previous version就结束了，但官方文档专门提醒，当前项目版本是在分析时确定的。使用Maven分析时，SonarQube会从`pom.xml`读取版本；使用Gradle分析时，会从`build.gradle`读取版本；其他情况则需要显式设置`sonar.projectVersion`。也就是说，如果你想用版本作为新代码边界，项目版本本身必须在分析链路里定义清楚。

4、三层配置关系一定要先理顺

SonarQube官方把配置层级讲得很明确。全局层只能设置Previous version和Number of days。项目层可以覆盖全局层。分支层又可以覆盖项目层。默认情况下，项目会继承全局基线，分支会继承项目设置。Specific analysis受限制，只能在分支层设置。这个层级关系不先搞清，后面你在项目里改了配置，却发现某个分支没变，往往就是被分支自己的定义覆盖了。

二、SonarQube新代码周期怎么切换

在SonarQube里切换新代码周期，本质上就是切换New Code Definition。官方当前做法很直接，项目管理员可以在UI里给项目或分支改新代码定义，也可以走Web API；只是Specific analysis这类更偏“人为指定分析点”的方式，官方要求通过Web API来设，不在普通UI中直接开放。

1、项目级切换走Project Settings

官方文档给出的标准入口是先进入目标项目，再到【Project Settings】【New Code】。在页面里的【Choose the baseline for new code for this project】区域，选【Define a specific setting for this project】，然后再选你要切换成的方式，比如Previous version、Number of days或Reference branch。这个动作就是项目级的新代码周期切换。

2、分支级切换在页面底部单独改

如果你不是想改整个项目，而是只想切某个分支，就要到同一页面底部的【Set a specific setting for a branch】区域。官方说明里，这里需要在目标分支那一行点编辑图标，再在弹出的对话框里选择该分支要用的新代码定义并保存。也就是说，分支周期切换不是去Branches页面随便改，而是在New Code页面里按分支逐个设。

3、Specific analysis要通过Web API切

官方写得很直接，Specific analysis只能通过Web API设置，因为它需要更频繁的人为维护，不适合直接放在UI里常规切换。当前文档给出的接口是`api/new_code_periods/set`，项目级调用时传项目参数，分支级调用时再加branch参数。要是你们的“新代码周期切换”其实是想把某次分析结果当成新周期起点，这条线才是正确做法。

4、Reference branch还可以在分析时覆盖

如果你的需求不是长期修改项目设置，而是某次分支分析临时指定参考分支，官方还支持在扫描时使用`sonar.newCode.referenceBranch`。这个参数会覆盖UI里全局或项目级的新代码定义，尤其适合第一次分析一个新分支时使用，因为此时该分支在SonarQube里还不存在，无法先在UI里单独配置。

三、SonarQube新代码设置先看哪里

很多团队不是不会切换新代码周期，而是切完以后结果和预期不一致。真正稳妥的做法，是先确认当前项目交付模式，再确认版本号或参考分支有没有在分析链路里真正生效，最后再回头看是不是被更高优先级的分支配置覆盖了。顺序理清以后，New Code这套逻辑其实并不复杂。

1、先看当前项目是按版本发版还是按天滚动

如果项目本来就有清晰版本号，却把新代码定义成Number of days，结果往往会跟版本发布节奏脱钩。反过来，如果项目持续交付、没有稳定版本边界，还坚持用Previous version，也容易让新代码范围不够贴合实际。官方推荐本身就是按项目类型来选定义方式，所以这一步必须先想清。

2、再看版本号或参考分支是否真的被分析用到

Previous version依赖项目版本。Reference branch依赖分析时本地仓库里存在对应分支，而且分支名要和SonarQube中一致。官方文档还提醒，Reference branch要正常工作，CI侧本地仓库必须取到参考分支代码。也就是说，周期切换看起来没问题，结果却不对时，很多时候不是UI没保存，而是分析输入条件没满足。

3、最后才看是不是层级覆盖了你的设置

项目继承全局，分支继承项目，但分支一旦有自己的定义，就会覆盖项目设置。官方已经把这层优先级写得很明确，所以你如果发现项目刚切成Number of days，某个分支却还是按Reference branch在算，新代码结果不一致，通常优先就该回到分支级设置去查。

总结

SonarQube怎么定义新代码，关键不是机械地选四种选项之一，而是先按项目交付方式决定到底用Previous version、Number of days、Specific analysis还是Reference branch。SonarQube新代码周期怎么切换，真正的入口则在【Project Settings】【New Code】里做项目级或分支级切换，Specific analysis走Web API，Reference branch还可以在分析时用参数覆盖。把项目节奏、分析输入和配置层级这三件事同时理顺后，SonarQube的新代码周期才会真正稳定下来。