从0到1实现新建需求功能：数据库设计、接口幂等与防重复提交

前几天排迭代，产品经理突然提了一句：“在项目后台加一个‘新建需求’的功能，让业务方自己提交，省得天天邮件来回问。”这话听着轻巧，真正动手做的时候，从字段定义到状态流转，从后端接口幂等性到前端防重复提交，我前后踩了不少坑，代码改了三版才顺完。回头看，“新建需求”绝不是一个普通的增删改查，它承载着整个项目协作流程的入口，值得认真拆一下。

这篇文章不是一个抽象的需求分析文档，而是以我做这个功能时的真实过程为主线，讲清楚“新建需求”背后的业务边界、数据库设计、接口实现以及最容易翻车的几个细节。无论你是后端开发、前端开发，还是需要评审功能的产品经理，应该都能在对应的环节找到可参考的东西。文章里给的表结构、接口约定和代码片段，都是基于我在项目里实际验证过的做法，可以直接抄，但抄之前记得先理解为什么这么设计。

1. 先把“新建需求”的功能边界理清楚

1.1 为什么这么简单的功能也要先做业务推演

很多开发看到“新建需求”四个字，第一反应是：给一张表单，字段有标题、描述、优先级，提交后insert进数据库，完事。我第一版就是这么干的，结果被产品和测试联合打回了一次，原因很实在：我没有回答“谁在什么时候用什么身份创建一个什么样的需求”。

在没有明确业务规则前就动手写代码，是这类功能最常见的项目风险。新建需求看起来入口简单，但实际参与者至少有四类：

• 业务方：不会操作复杂系统，更不想看“需求编号”，只希望快速记录自己想要什么。
• 产品经理：需要从业务描述中提炼出一份能进入研发排期的需求单，所以他要看编辑痕迹、来源渠道、期望时间。
• 研发负责人：关心需求是否经过了字段校验、有没有明确优先级、是不是已经有人认领。
• 系统管理员：关心权限边界，不能让人随便改别人的需求单。

我处理的这个场景里，“新建需求”其实是需求管理模块的起始动作，后面还跟着需求评审、排期、开发、测试、验收这一串流程。新建时没有把基础字段定好，后面每一个环节都会很别扭，比如研发想看期望上线时间，业务方没填，状态没法自动流转，因为初始状态根本就没定清楚。

所以做这个功能前，我建议先花半小时画一下最小闭环：用户从哪个页面进来、点击后发生什么、数据落在哪张表、创建之后谁会收到通知、后续哪个操作会变更它的状态。只要这条链路清晰了，后面填代码就只是时间问题。这半小时不是浪费时间，是帮你把“想当然”的风险挡在编码之前。

1.2 字段设计不是越多越好，但遗漏常用字段更麻烦

新建需求表单的第一版我做了十个字段，看起来挺全，但里面的问题很多。比如我放了一个“需求分类”的下拉框，备选项是“功能优化”“缺陷修复”“技术升级”，结果业务方根本不知道怎么选，他只知道“首页的按钮不好用”。另一类问题是不小心漏了“影响版本”和“当前状态”，导致开发在详情页看到需求后还得去群里面问，沟通成本又上去了。

后来我把字段分为三层来设计：

• 必填层：需求标题、需求描述、提出人、期望日期。这四样是能不能进入后续环节的基础，描述不能只写“做一个报表”，至少要支撑产品经理看懂用户诉求。
• 选填层：优先级、需求来源、关联业务模块、附件。这些字段不是每次都填，但有的时候能大幅提升处理效率。
• 系统层：需求单号、状态、创建人、创建时间、更新人、更新时间、当前处理人。这些字段用户不需要填，但后端必须自动生成，否则后面查历史、做流转时非常痛苦。

具体到字段校验，也不要全交给前端。我碰到过一个场景：产品经理在Web端填了很长的需求描述，提交后通过了前端最大长度校验，但后端没限制，结果直接写入接口导致数据库报错，后来发现页面与接口用的校验规则不一致。合理的做法是前后端各做一遍，前端为体验，后端为数据安全。

字段清单稳定下来后，我整理了一个需求核心字段表，给产品确认了一次，也是在给后续开发定契约。

这张表是给后端建表用的基线，但它本质上回答的是产品功能问题。真正动手前把它对齐，最大的好处是减少后期大量返工。

2. 从数据库到接口的设计要点

2.1 表结构设计要照顾新增和后续查询的效率

既然确定“新建需求”是需求管理入口，那么表结构必须一开始就往后续流程方向设计，而不是只服务这一个新建动作。我选择的表名是requirement，使用UTF-8的utf8mb4字符集，避免用户填的表情符号存不进去。主键用自增id，同时提供一个业务上直接可读的需求编号req_no，唯一索引设在这个字段上。

这里有个容易忽略的点：需求编号不要用数据库自增id裸奔给用户看，那会泄露系统内部数据量。我采用“前缀+日期+每日序号”的方式生成，例如REQ-20250112-001，生成逻辑从一张序号表或者Redis自增键里取。项目规模不大时，用数据库select count容易出并发问题，稳妥一点的方案是独立一个序号表，或者用Redis的incr，然后每天零点重置。

建表时也要考虑“新建”这个场景下可能产生的大字段。附件和富文本描述，我会选择从主表里拆出去，附件单独建一张requirement_attachment表，需求描述如果可能很大，也考虑放在另一张扩展表里，主表只保留常用查询字段。否则等需求列表页加筛选的时候，一查大字段性能就会很难看。

下面是一份符合我落地方案的表结构，大家可以根据自己项目的用户量适当调整字段长度和索引：

sql复制CREATE TABLE `requirement` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键',
  `req_no` varchar(32) NOT NULL COMMENT '需求单号',
  `title` varchar(200) NOT NULL COMMENT '需求标题',
  `description` text COMMENT '需求描述',
  `priority` tinyint(4) NOT NULL DEFAULT '2' COMMENT '优先级 1高 2中 3低',
  `source` varchar(32) DEFAULT NULL COMMENT '需求来源',
  `expect_finish_date` date DEFAULT NULL COMMENT '期望完成日期',
  `status` varchar(20) NOT NULL DEFAULT 'draft' COMMENT '状态：draft待提交，submitted已提交，reviewing评审中',
  `handler_id` bigint(20) DEFAULT NULL COMMENT '当前处理人',
  `creator_id` bigint(20) NOT NULL COMMENT '创建人',
  `created_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_req_no` (`req_no`),
  KEY `idx_status_priority` (`status`, `priority`),
  KEY `idx_creator_id` (`creator_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='需求表';

我在实际落表时还加了一个deleted逻辑删除字段，但为了模板简洁没贴出来。新建接口虽然只做插入，但查询列表、校验需求号是否存在时会频繁用到索引，所以req_no唯一索引、status普通索引都很必要。如果团队后续会根据创建人筛选我的需求，那creator_id索引也得早建。

2.2 状态机的初始状态别写死在代码里

新建需求一定是整个状态流里的第一个节点，常见的状态初始化可选“草稿”或“已提交”。如果系统走“先保存再提交”，那初始状态是草稿；如果页面只有一个提交按钮，那初始状态直接就是“已提交”。这两个选择对后续的权限影响很大，比如草稿只有创建人可见，已提交之后产品经理才能介入编辑。

我这次的需求更贴近“业务方直接提交”的场景，所以新建时后端的初始状态设为submitted，而不是让前端传一个状态字段。这里有一个重要的安全原则：初始状态只能由后端代码设置，不能信任前端传参。我见过有人很自然地在请求体里带上“status: 2”，万一用户把状态传成“已完成”，就会出现刚创建的需求跳过评审直接完成的情况。

如果项目里以后还要演化出多个流程，建议一开始就把状态定义成枚举或一张独立的状态字典表，不要让字符串在代码里到处飘。用常量的好处是编辑器可以直接提示，不会因为拼写错误导致脏数据。

java复制public enum RequirementStatus {
    DRAFT("draft", "草稿"),
    SUBMITTED("submitted", "已提交"),
    REVIEWING("reviewing", "评审中"),
    APPROVED("approved", "已通过"),
    REJECTED("rejected", "已拒绝");
    // 省略 getter...
}

新建需求这段逻辑里，我会要求Service里把状态设置为枚举值，比如RequirementStatus.SUBMITTED.getCode()，而不是直接写字符串，这样后续任何一个环节引用状态时都不会出现不一致。

3. 实操过程：从后端接口到前端表单的完整落地

3.1 接口协议：一个POST请求要考虑的边界条件

确定后端接口时，我采用REST风格：POST /api/requirements，用于创建一条新需求。请求体里只接收业务字段，不需要接收creatorId，也不需要接收status，这两个字段在后端从当前登录上下文和状态枚举里取。前端传过来的数据必须经过校验，比如标题不能为空白、描述不能超过设定长度、期望日期不能早于今天。

接口返回时，除了返回创建成功的数据，我更建议把需求编号一起返回，因为页面提交成功之后通常会弹出一个成功提示，提示里如果带上“需求号REQ-20250112-001已创建”，用户会有很强的安全感。这块视觉上的交互小细节，是之前没有做，后来运营反馈“提交了跟没提交一样”才补上的。

一个完整的请求响应示例大概是这样的：

json复制// 请求 POST /api/requirements
{
  "title": "在首页增加下载报表入口",
  "description": "运营希望用户可以在首页看到最近一周的报表下载入口，减少人工客服传递。",
  "priority": 1,
  "source": "客户反馈",
  "expectFinishDate": "2025-03-01",
  "attachmentIds": [12, 13]
}

// 响应 200
{
  "code": 0,
  "data": {
    "reqNo": "REQ-20250112-001",
    "title": "在首页增加下载报表入口",
    "status": "submitted"
  }
}

后端接口里还有一个很容易忽略的问题是幂等性。用户在网络慢的时候连续点了两次“提交”，前端如果没拦住，后端可能会插入两条几乎一样的需求。解决的办法有两种，第一种是前端提交时按钮禁用，第二种是后端校验标题+提出人+时间窗口内是否已有相似记录。两种我都用了，后端兜底更稳。更严格的做法是前端生成一个clientToken，把它作为唯一键传给后端，后端利用数据库唯一索引或Redis setnx来防止同一请求被处理多次，不过大部分内部系统按标题+创建人做短时间内的重复校验就够了。

3.2 Service层代码：事务、日志和通知不能省

后端代码不是只做一个mapper.insert。我在实际开发中把核心逻辑写进了Service层，并且加了事务控制。因为新建需求除了插入主表，还要保存操作日志、可能更新需求序号、触发通知消息。这些操作如果没有同时成功或同时失败，会出现数据不一致。

核心Service方法我用Java伪代码来展示，重点不是语法，而是每一步背后的意图：

java复制@Transactional(rollbackFor = Exception.class)
public RequirementVO create(RequirementCreateRequest req) {
    // 1. 二次校验，防止绕过前端直调接口
    requirementValidator.validate(req);

    // 2. 生成业务需求单号，例如 REQ-20250112-001
    String reqNo = requirementNoGenerator.generate("REQ");

    // 3. 构建实体并设置初始状态
    Requirement requirement = RequirementAssembler.toEntity(req);
    requirement.setReqNo(reqNo);
    requirement.setStatus(RequirementStatus.SUBMITTED.getCode());
    requirement.setCreatorId(SecurityUtils.getCurrentUserId());
    requirement.setHandlerId(SecurityUtils.getCurrentUserId());

    // 4. 保存主表
    requirementMapper.insert(requirement);

    // 5. 保存附件关联关系
    if (CollectionUtils.isNotEmpty(req.getAttachmentIds())) {
        attachmentService.bindRequirement(requirement.getId(), req.getAttachmentIds());
    }

    // 6. 记录操作日志：谁在什么时候创建了这条需求
    operationLogService.record("requirement", requirement.getId(), "create", "新建需求");

    // 7. 触发通知给需求处理人员
    notifyService.sendRequirementCreatedNotice(requirement);

    return RequirementAssembler.toVO(requirement);
}

这一步能展开的细节很多。比如第7步发通知，绝对不能放在数据库事务里直接调外部接口，否则外部接口响应慢会把整个请求拖垮。我在最初就是这么做的，后来对方通知服务超时，新建需求接口也跟着变慢。正确做法是先把通知事件写入本地消息表，或者依赖消息队列异步发送，哪怕只用Spring的@Async也比同步调用稳定。步骤5里绑定附件关联关系，同样也不适合在请求里先传一堆附件内容，新建时最好只保存附件ID，文件上传走独立的接口。

事务这块还有一个心得：如果系统里用MySQL并且默认隔离级别是REPEATABLE_READ，高并发下相同的需求单号生成逻辑可能受事务可见性影响。我这次用的是Redis incr加日期前缀，因此没遇到这个坑；但如果用数据库查最大序号再+1的方式，一定要给序号表或者需求表加锁，否则并发时就会造出重复单号，等唯一索引报错再重试就很被动了。

3.3 前端表单：按钮、校验与用户体验的配合

前端我这次用Vue 3和Element Plus实现一个新建需求的抽屉表单。之所以不选择独立页面，是因为用户在需求列表页更希望快速录入，抽屉可以减少跳转感，减少用户对需求的“打断感”。如果需求本身内容很长，那可以换成独立页面，这个要考虑产品整体交互习惯。

页面上的关键点是提交前校验。Element Plus的表单校验可以配置规则，比如必填项：除了常规非空检查，标题还要去掉首尾空格后判断；期望日期加上大于今天的自定义校验，否则用户选择了过去的日期，后端又要返工。

我截取了一个简化版本的页面逻辑，核心是提交防重复：

vue复制<template>
  <el-form ref="formRef" :model="form" :rules="rules" label-width="100px">
    <el-form-item label="需求标题" prop="title">
      <el-input v-model="form.title" maxlength="100" show-word-limit />
    </el-form-item>
    <el-form-item label="需求描述" prop="description">
      <el-input type="textarea" :rows="5" v-model="form.description" />
    </el-form-item>
    <el-form-item label="期望日期" prop="expectFinishDate">
      <el-date-picker
        v-model="form.expectFinishDate"
        type="date"
        value-format="YYYY-MM-DD"
        :disabled-date="disabledDate"
      />
    </el-form-item>
  </el-form>
</template>

<script setup>
const submitLoading = ref(false)

const submit = () => {
  formRef.value.validate(async (valid) => {
    if (!valid) return
    if (submitLoading.value) return
    submitLoading.value = true
    try {
      const data = await createRequirement(form.value)
      ElMessage.success(`提交成功，需求编号：${data.reqNo}`)
      emit('success')
    } finally {
      submitLoading.value = false
    }
  })
}
</script>

disabledDate里限制只能选今天和未来日期，比后端返回“日期不能早于今天”的报错体验好很多。不过前端校验再多也不能替代后端校验，始终要默认调用方可能绕过页面直接请求，所以后端校验必填和日期逻辑是底线。

需要注意的一点是：在点击提交之后一定先把按钮置灰，或者用一个submitLoading字段拦截二次点击。真实场景里用户会连点鼠标，一旦第一个请求还没返回，第二个请求进来，前端往往会重复提交。这个问题在新建需求里最常见，也是我之前被测试反复复现的bug。后来我把提交按钮上加了一个v-loading效果，基本杜绝了正路操作下的重复表单。

4. 常见问题与排查技巧实录

4.1 新建需求过程中容易翻车的几个问题

开发完成不等于功能可靠。我在自测和上线后的反馈里，把“新建需求”遇到的高频问题整理成了一张速查表，方便你们后面排查时有个大概方向。

这张表里的每一个问题我都真实见过。特别是“提示提交成功但列表查不到”那次，排查时最头疼：请求返回正常，数据却消失。后来发现是事务里附件关联插入失败抛了异常，整个创建逻辑回滚了，但全局异常处理器没有把异常信息返回给前端，前端只看到200 OK。解决方案就是把自定义异常的响应码和消息包装好，前端判断业务码，不能只判断HTTP状态码。

4.2 排查“新建”慢或超时的定位思路

如果只是给自己维护的内部系统加一个新建需求功能，性能压力一般不会太大。但一旦使用人数变多，可能有人反馈“点击保存之后等了很久”，这时候从哪里查？我的习惯是打开后端日志，看这个请求的耗时分布。最常见的原因不是SQL慢，而是同步发送通知导致的问题，所以新建功能里尽量不要直接调通知服务。

另一个容易被忽略的慢点是附件上传。如果你的“新建需求”里包含附件上传，但是附件在点击提交时才传到后端，那么网络差时整个表单会变得很长。比较好的做法是把附件上传独立成异步接口，拿到的文件ID放在表单里，最后新建时只提交ID列表。这样文件上传失败不会影响表单其他内容的填写，用户感知也好很多。

如果排查时发现插入主表就很慢，优先检查索引数量和锁等待。requirement表在插入时本身没有太大性能瓶颈，但如果有大量外部事务持有某一行锁，或索引设计冗余，也可能受到影响。建立一个最小可复现环境，在数据库客户端直接执行同一条insert语句，就能快速确认是不是SQL层面的硬伤。

4.3 权限校验不要只靠隐藏按钮

前端根据角色隐藏“新建需求”按钮是一个非常常见的做法，但它只是体验层面的控制。如果用户通过工具直接调用接口，权限限制就失效了。我这次在设计权限时，后端通过Spring Security的@PreAuthorize注解，或者手动判断当前用户角色，把“创建客户需求”这个权限单独抽出来，没有权的人调用接口时统一返回403。

另外，创建完成之后，“当前处理人”字段我默认设置成创建人自己，但这不等于创建人可以为所欲为。后续编辑、删除、状态流转的权限，要单独在各自接口中重新校验。我在这个项目里吃过一次亏：C用户通过越权方式把别人创建的需求状态直接改成已通过，就是因为后端只校验了登录状态，没有校验资源归属。新建接口虽然相对安全，但权限设计要放在整个需求生命周期里去思考，不是新建完就结束了。

5. 上线后的复盘：三个容易被忽视的细节

“新建需求”功能跑通并上线用了三个迭代，回头看真正提升体验的并不是堆了多少代码，而是对几个细节的处理。第一个细节是成功后的提示要有“编号意识”。我上线初期只提示“提交成功”，很多用户记不住自己填了什么，过两天来问“我提交的那个功能怎么还没消息”。加上需求单号后，用户手上有了一个可跟踪的凭证，后续沟通效率明显高了不少。

第二个细节是模板和草稿能力。业务方填需求描述时，经常不知道怎么写才算完整。我后续在表单里加了一个“描述引导模板”，把“背景、现状问题、期望结果”三个字段模板化，用户照着填基本不会出现“帮我做个功能”这种一句话需求。如果你不希望一上来引入过于复杂的草稿状态机，这个模板引导的轻量方案非常推荐。

第三个细节是数据看板里的来源统计。新建需求时我们记录了来源和优先级，这不仅仅是流程表单信息。上线一个月后，我把这些数据做了个简单汇总，可以看到“客户反馈”类需求占比很高，对产品规划非常有价值。所以新建需求功能的字段，其实就是业务洞察的基础，设计时不要随手写死，要想明白每个字段时间长了能告诉你什么。

做这类功能，我一直有个体会：代码本身并不难，难的是把看似确定的东西拆出足够多不确定项，一个个找产品确认。如果你接到“新建需求”这个需求，不要急着写接口，先问清楚状态从哪里开始、用户是谁、提交后谁接收、重复点怎么处理。四个问题都对齐了，这个功能基本就成功了一半。