七匹狼——β阶段代码规范

目录

一、规范适用范围

本规范适用于“食话说”项目 β 阶段的前端代码、后端代码、数据库脚本、测试代码、接口文档、配置模板、工作项和 Git 提交。规范的目的不是增加形式要求，而是让不同成员编写的代码能够被其他成员理解、运行、测试和维护。

项目采用分层 Web 应用设计，数据库使用 PostgreSQL 16，Redis 7.2 用于缓存或可重建的派生数据。具体依赖和目录以代码仓库中的实际构建配置为准。

下面的代码片段以“食话说”的店铺、标签、推荐和评论功能为例，用于说明本规范要求的写法。示例用于展示编码约定，不代表对仓库中当前实现状态的单独证明；实际接口、字段和类名仍以项目代码和设计文档为准。

二、通用编码原则

1. 先理解再修改。 修改已有模块前先阅读相关接口、数据结构、测试和调用关系，不直接覆盖不熟悉的代码。
2. 保持单一职责。 页面负责展示和交互，Controller 负责请求接收，Service 负责业务规则，Repository 或数据访问层负责数据读写。
3. 优先复用已有约定。 不为一次性需求重复引入框架、依赖或相似工具。
4. 不提交敏感信息。 密码、令牌、个人信息和真实密钥不得写入代码、日志、测试截图或提交记录。
5. 所有修改都要可验证。 功能完成后至少执行编译、接口测试、页面检查、数据库脚本检查或相应的文档核对。
6. 保持修改范围清晰。 不在功能提交中混入无关格式化、批量重命名或未经讨论的重构。

2.1 β 阶段的完成标准

β 阶段的“完成”同时包含实现、验证和说明三个部分：

只有实现、验证和说明都完成，任务才能标记为已完成；如果其中一项暂时缺失，应记录为进行中或待验证，而不是直接关闭任务。

三、目录和模块边界

项目按实际仓库结构组织，原则上保持以下边界：

接口字段、数据库字段和页面显示名称需要保持一致。新增模块必须说明所属层次、输入输出和依赖关系。

四、后端 Java 代码规范

4.1 命名规范

命名示例：

public class ShopRecommendationService {
    private static final int MAX_QUERY_LENGTH = 60;

    public List<ShopSummary> findMatchedShops(ShopSearchRequest request) {
        // 根据请求条件调用业务规则和数据访问层
        return List.of();
    }
}

上例中，类名说明了服务对象，常量说明了限制含义，方法名说明了动作和返回内容。以下写法不采用：

class shopservice {
    int n = 60;

    List<Map<String, Object>> getData(Map data) {
        return null;
    }
}

反例的问题在于类名、变量名和方法名不能表达业务含义，核心数据通过无约束的 Map 传递，后续成员难以判断字段是否完整。

4.2 实现要求

• 方法参数、返回值和异常情况要能够从命名或注释中理解；
• 不使用含义不清的单字母变量，循环下标等局部变量除外；
• 复杂的推荐、匹配和审批规则拆成可单独测试的方法；
• 参数校验、权限校验和业务处理按顺序执行，错误时返回统一格式；
• 日志记录必要的任务标识和错误原因，不记录密码、令牌和完整个人信息；
• 资源操作、事务操作和外部服务调用要考虑失败后的处理方式。

分层调用示例：

@RestController
@RequestMapping("/api/v1/recommendations")
public class RecommendationController {
    private final RecommendationService recommendationService;

    @PostMapping
    public RecommendationResponse recommend(
            @Valid @RequestBody RecommendationRequest request) {
        return recommendationService.recommend(request);
    }
}

Controller 只负责接收请求和返回结果，推荐条件的解析、标签匹配和排序放在 Service 中：

@Service
public class RecommendationService {
    public RecommendationResponse recommend(RecommendationRequest request) {
        validateRange(request.getBudgetMin(), request.getBudgetMax());
        List<ShopCandidate> candidates = shopRepository.findCandidates(request);
        return rankingService.rank(candidates, request.getTasteTags());
    }
}

不建议把数据库查询、排序规则和页面文案全部写进 Controller：

@PostMapping("/bad-example")
public Object badExample(@RequestBody Map<String, Object> body) {
    // Controller 中直接拼接 SQL、判断标签并生成页面文案
    return shopRepository.query("select * from shop where ...");
}

这种写法会使接口层承担过多职责，测试时也难以分别验证参数校验、匹配规则和数据访问。

4.3 业务代码编写要求

• Controller 不直接编写复杂的推荐、标签匹配和评论分析规则；
• Service 方法的参数和返回值要能够表达业务含义，避免用多个无名称的 Map 传递核心数据；
• 对推荐排序、标签命中、排除原因和审批状态等规则使用清晰的枚举或专用对象表示；
• 不把数据库字段名、权限值和错误信息散落成魔法字符串；
• 涉及多个表的状态变化必须明确事务范围和失败后的回滚方式；
• 对空结果和数据不足进行正常处理，不能用默认数据掩盖查询失败；
• 修改接口返回结构时，同时检查前端调用、测试用例和接口说明。

业务结果建议使用有含义的对象表示，而不是返回多个无法区分的数字：

public record MatchResult(
        long shopId,
        int matchedTagCount,
        boolean excluded,
        String excludeReason) {
}

public record RecommendationItem(
        long shopId,
        double score,
        List<String> reasons) {
}

例如，预算不合法时应在参数校验阶段结束请求，而不是把异常输入继续传给排序逻辑：

private void validateRange(BigDecimal min, BigDecimal max) {
    if (min != null && min.signum() < 0) {
        throw new BadRequestException("最低预算不能为负数");
    }
    if (min != null && max != null && min.compareTo(max) > 0) {
        throw new BadRequestException("最低预算不能高于最高预算");
    }
}

五、前端代码规范

• 组件名称使用大驼峰，变量和方法使用小驼峰；
• 页面组件只负责展示和交互，接口访问集中管理；
• 文本、颜色、按钮状态和错误提示保持统一；
• 每个异步请求都要处理加载、成功、空数据和失败状态；
• 不使用固定店铺名称、固定列表位置作为自动化测试的唯一定位条件；
• 表单提交前进行长度、格式和范围校验，提交后明确提示成功或失败；
• 页面不能因为接口返回空数组、字段缺失或外部服务失败而直接崩溃。

5.1 页面状态和交互细节

页面实现至少明确以下状态：

页面自动化测试应优先使用稳定的元素标识、接口返回数据或明确筛选条件，不以固定店铺名称、固定排序位置或截图像素作为唯一判断条件。

页面请求示例：

const loading = ref(false)
const shops = ref([])
const errorMessage = ref('')

async function loadRecommendations(query) {
  loading.value = true
  errorMessage.value = ''
  try {
    shops.value = await recommendationApi.search(query)
  } catch (error) {
    errorMessage.value = '推荐结果加载失败，请稍后重试'
  } finally {
    loading.value = false
  }
}

页面模板需要区分加载、空数据和错误状态：

<div v-if="loading">正在加载推荐结果……</div>
<div v-else-if="errorMessage">{{ errorMessage }}</div>
<div v-else-if="shops.length === 0">暂时没有符合条件的店铺</div>
<ShopCard
  v-else
  v-for="shop in shops"
  :key="shop.shopId"
  :shop="shop"
  :data-shop-id="shop.shopId"
/>

自动化测试可以使用 data-shop-id 或其他稳定标识：

await page.locator('[data-shop-id="1001"]').click()
await expect(page.getByText('店铺详情')).toBeVisible()

不建议这样定位：

await page.locator('.shop-list > div:nth-child(2)').click()

固定第二个列表项会随着排序和数据变化失效，不能稳定证明详情流程正确。

六、PostgreSQL、Redis 和数据脚本规范

1. 表名、字段名使用统一的小写和下划线命名方式，字段含义与数据字典一致。
2. 每张业务表明确主键，外键、唯一约束、非空约束和状态字段按业务需要设置。
3. 时间字段明确时区和含义，不能用一个字段同时表示创建时间和更新时间。
4. 用户标签、店铺标签和菜品标签的关系通过明确的关联表表达，避免把多值内容随意拼接在一个字段中。
5. 初始化数据、测试数据和正式业务数据分开管理，测试数据不得包含真实密码或未授权的个人信息。
6. 数据导入和清洗脚本要说明输入格式、转换规则、异常处理和重复数据处理方式。
7. Redis 只保存可重建或有明确失效策略的数据，缓存键要包含必要的用户或业务对象标识，避免不同用户之间相互污染。
8. 数据库脚本执行后要进行字段、数量、关联关系和接口结果核对。

表结构示例：

CREATE TABLE shop (
    shop_id BIGINT PRIMARY KEY,
    shop_name VARCHAR(120) NOT NULL,
    avg_price NUMERIC(8, 2),
    created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE shop_tag (
    shop_id BIGINT NOT NULL REFERENCES shop(shop_id),
    tag_id BIGINT NOT NULL REFERENCES tag(tag_id),
    PRIMARY KEY (shop_id, tag_id)
);

用户标签、店铺标签和菜品标签属于多对多关系时，应使用关联表表达。以下写法不建议采用：

ALTER TABLE shop ADD COLUMN tags TEXT;
-- 例如把“清淡,实惠,距离近”拼成一个字符串

把多个标签拼在一个字段中会增加查询、去重、修改和外键约束的难度，也不利于统计标签命中次数。

缓存键示例：

recommendation:user:102400320:budget_30:tag_spicy:v1

缓存键需要包含用户或请求条件等必要标识，并设置明确的过期时间。不能使用所有用户共用的模糊键，例如 recommendation:last，否则可能出现用户之间的推荐结果相互污染。

6.1 数据库变更流程

数据库字段或关系发生变化时，按以下顺序处理：

1. 说明变更原因和涉及的业务功能；
2. 更新建表或迁移脚本、数据字典和接口字段说明；
3. 检查初始化数据、测试数据和已有查询是否受到影响；
4. 执行建库、迁移、查询和回滚验证；
5. 将验证结果与工作项和提交记录关联。

不直接在测试环境手动修改表结构后把结果当作正式版本，避免成员之间出现“只有某台环境能运行”的情况。

数据库变更记录示例：

变更原因：店铺详情需要保存平均消费和更新时间
影响表：shop
新增字段：avg_price NUMERIC(8,2)、updated_at TIMESTAMPTZ
同步内容：建表/迁移脚本、数据字典、详情接口 DTO、前端展示和测试数据
验证方式：执行迁移脚本，查询字段，调用详情接口并检查页面展示
回滚方式：删除新增字段并恢复对应接口和页面版本

七、接口、异常和安全规范

接口设计遵循“输入明确、响应统一、错误可解释”的原则：

推荐接口至少检查完全匹配、部分匹配、无匹配、忌口冲突、预算异常、距离异常和空输入；评论分析接口至少检查有评论、评论不足、数据异常和服务失败。

统一响应示例：

{
  "code": "OK",
  "message": "success",
  "data": {
    "items": [],
    "total": 0
  }
}

参数错误示例：

{
  "code": "INVALID_ARGUMENT",
  "message": "最低预算不能高于最高预算",
  "data": null
}

错误响应只提供用户能够理解的提示，不返回 SQL、堆栈、服务器路径或内部配置。未登录访问管理接口时，即使前端没有显示入口，服务端仍必须拒绝请求。

7.1 接口修改检查清单

接口发生变化时，提交者需要逐项确认：

• 请求路径、方法、参数名称和参数类型是否变化；
• 正常响应、空响应和错误响应是否仍符合统一格式；
• 身份认证和角色权限是否仍然有效；
• 前端调用、接口示例和自动化测试是否同步；
• 错误信息是否足够定位问题，但没有暴露内部实现；
• 对应的工作项、提交记录和测试结果是否已经更新。

八、测试和质量检查规范

测试覆盖正常路径、边界输入、空数据、权限错误和依赖服务异常五类场景。β 阶段重点补充 PostgreSQL 数据库测试、并发审批、缓存隔离、重复提交、未登录访问和页面自动化验收。

提交前检查：

• 新增业务方法有对应的单元测试或接口验证记录；
• 数据库脚本能够执行，字段和接口返回保持一致；
• 页面能够显示加载、成功、空数据和错误状态；
• 权限错误和异常输入不会泄露内部信息；
• 修复缺陷后重新执行受影响功能的回归测试；
• 测试结果记录通过、失败、挂起、跳过和未执行的数量及原因。

8.1 测试命名和结果记录

测试名称应体现“条件—操作—预期结果”，例如“预算为负数时推荐接口返回参数错误”“未登录访问管理接口时拒绝请求”。测试记录至少包括前置条件、输入数据、执行步骤、预期结果、实际结果和结论。

对于挂起或未执行的测试，必须说明原因和后续安排。不能只保留通过数量而忽略未执行的数据库、权限或外部服务测试。

测试用例示例：

测试编号：REC-004
测试名称：预算下限高于上限时返回参数错误
前置条件：推荐服务已启动，用户已进入推荐页面
输入数据：budgetMin=50，budgetMax=30
预期结果：接口返回 INVALID_ARGUMENT，不查询店铺列表，页面显示预算范围提示
实际结果：填写实际执行结果
结论：通过 / 失败 / 挂起 / 未执行

对应的单元测试示例：

@Test
void shouldRejectWhenMinimumBudgetIsGreaterThanMaximumBudget() {
    RecommendationRequest request = new RecommendationRequest(
            new BigDecimal("50"), new BigDecimal("30"), List.of());

    assertThatThrownBy(() -> recommendationService.recommend(request))
            .isInstanceOf(BadRequestException.class)
            .hasMessage("最低预算不能高于最高预算");
}

测试不能只验证返回状态码，还应确认错误情况下没有产生不应有的数据库写入或缓存记录。

九、Git、工作项和代码评审规范

9.1 分支和提交

• 主分支只保留经过验证的可交付版本；
• 每个功能或缺陷建立对应工作项，再创建任务分支；
• 分支名称体现任务性质和编号，例如 beta/issue-编号-主题；
• 提交信息使用统一格式：类型(工作项编号): 简短说明；
• 常用类型包括 feat、fix、test、docs 和 refactor；
• 一个提交尽量只对应一个清晰目的，不提交编译产物、临时文件和敏感配置；
• 提交后关联工作项，说明修改内容、验证方式和已知限制。

提交示例：

feat(71193280): 完善推荐接口预算范围校验
fix(71193280): 修复评论为空时页面崩溃
test(71193280): 增加推荐接口边界用例
docs(71193280): 更新接口字段和运行说明

不建议使用以下提交信息：

修改一下
最终版
test

这类信息无法说明修改对象、工作项和验证范围，后续排查问题时也难以定位。

9.2 评审和合并

提交者先自查，协作成员再进行代码阅读或联调验证。合并前至少确认：功能范围没有扩大、接口和数据库字段没有不一致、测试已经执行、异常处理存在、文档和截图需要更新的部分已经同步。

代码评审示例：

9.3 提交前检查表

9.4 工作项与提交内容的对应关系

β 阶段不以“提交过代码”直接判断任务完成，而是要求工作项、提交和验证结果能够相互对应。一个功能工作项至少应包含以下内容：

涉及接口或数据库的修改，提交前还要检查前端请求参数、后端返回结构、数据库字段和测试数据是否保持一致。涉及页面的修改，要同时检查加载中、空数据、失败和权限不足等状态，避免只验证正常路径。

十、AI 技术员协作规范

AI 可以作为设计师、程序员和测试员辅助团队工作，但不能替代成员对需求、代码和结果负责。

AI 协作流程统一为：明确背景和边界 → 给出验收标准 → 生成方案或初稿 → 人工筛选和修改 → 编译或测试验证 → 记录采纳内容和遗留问题。提示词中不得包含真实密码、令牌、个人隐私或未经授权的数据。AI 生成的代码必须由成员理解、验证和维护，不能直接合并。

10.1 AI 输出记录格式

每次重要的 AI 协作至少记录以下内容：

AI 提供的是候选方案，不是事实来源。版本号、依赖、接口、字段和外部资料必须由成员实际核对。

AI 协作示例：

任务背景：推荐接口需要补充预算范围和空结果处理。
约束条件：使用现有 Spring Boot 分层结构，不修改数据库表，不改变成功响应字段。
验收标准：预算下限大于上限时返回统一参数错误；无匹配店铺时返回空列表；正常请求保持原有响应结构。
请给出参数校验、异常响应和测试用例建议，并标出需要人工确认的假设。

人工处理过程：先检查 AI 是否误解现有响应结构，再结合项目代码修改示例；随后由成员编译项目，执行边界测试和接口测试。若 AI 建议引入新依赖、修改未授权模块或与实际字段不一致，则不直接采用。

十一、β阶段团队角色

十二、结语

β 阶段的代码规范重点是让代码、数据、测试、工作项和交付材料能够相互对应。七匹狼团队将按照统一的命名、分支、提交、评审和测试规则推进开发，并以实际运行结果作为判断功能完成的依据。