企业官网建设流程全解析

我几个月前参加了一个内部小项目，任务卡上就写了三个字母："rea"。问了一圈没人知道全称，后来我们索性把它解读成 Requirements & Experimental App——需求驱动的实验性应用。这个项目周期很短，从需求分析到前端落地再到联调上线，总共不到十天，但很多经验特别值得记下来。

这篇文章就是我对"rea"这个项目的完整复盘。它讲的不只是某个技术方案，更是一套可复用的做事方式：怎么把一个模糊到只有三句话的需求收敛成可交付的闭环；怎么在选型上不追新、只求稳；怎么用几十行代码把状态管明白；以及联调阶段真正会遇到的几个坑。适合正在做小型内部工具、管理短平快前端项目的朋友参考，也适合刚带小项目的同学避雷。

1. 代号"rea"的来历：从三行需求到一周交付的边界收敛

1.1 需求只有三行，为什么我们追问了四个小时

"rea"最初的需求原话大概是这样：做一个登记页面，能录数据，能查数据，要落库，最好一周内上线。三句话，听着简单，但真动起手来，处处都是问题。

我记得那天下午，我们四五个人围在一起，对着这三行字问了一轮又一轮。第一轮是问使用场景：谁在用？大概多少人？数据量一个月有多少条？回答是内部约二十人使用，高峰期并发也就个位数，一年几千条记录。听完这个我就放心了，这不是一个需要高并发架构的项目，一切从简是没问题的。

第二轮问业务规则：有哪些字段需要登记？谁能修改删除？要不要权限区分？要不要导出？要不要按角色隔离数据？原需求一句都没提，但这些才是决定页面长什么样的关键。最后确认下来的字段是：名称、来源、状态、负责人、备注、创建时间；权限上全员可查看，管理员可编辑删除；导出需要做，统计报表先不碰。

第三轮问的是边界：有没有审批流？要不要附件上传？需不需要操作日志？这轮我们的策略很明确，凡是没人能说清具体场景的，一律砍掉或者标记为"暂不实现"。比如审批流，问了一圈，实际业务里根本没这个流程，纯粹是猜想出来的需求。附件上传要做也不难，但会引入存储策略和文件预览的复杂度，一周内没必要碰。

1.2 边界收敛之后得到的最小闭环

四小时追问之后，"rea"的范围就非常清楚了：录入表单、列表展示与筛选、详情查看、导出。就这四个功能。我们把这个结果写进任务卡，对比图大概是这样。

做完这张表，我心里是踏实的。因为所有模糊地带都有了明确结论，后续开发不会出现"这个东西要不要做"的反复扯皮。

动手之前我还做了一件小事：画数据流草图。就一张纸，箭头从表单指向接口，从接口指向列表，从筛选条件拉一条线到列表查询逻辑。画完之后至少提前发现了两个问题：一个是"状态"这个字段，录入时和筛选时的取值到底用同一套枚举还是两套；另一个是列表的排序规则没有定义，后来补了一条"默认按创建时间倒序"。这些问题在草图上发现，成本几乎为零，等代码写一半才发现就得返工了。

2. 技术骨架选型：在稳定与快速交付之间找平衡

2.1 选型三条约束：团队熟悉度、复用、分层

"rea"项目最不缺的就是诱惑。有人提议上最新的组件方案，有人建议换一套响应式流式框架，还有人想自己搭一套微前端骨架。我作为实际负责人，一条条全否了。原因很简单：这个项目只有一周时间，团队核心成员就两三个人，目标是交付稳定可用的工具，不是做新技术试验田。

我给大家定了三条约束。第一条，团队熟悉程度优先于新特性。我们当前用的组件化技术栈已经跑了好几个项目，日常维护的人闭着眼都能写，没必要为了"新"而换。第二条，复用大于创造。公司内部已经有一套成熟的工程脚手架，直接拿来改造，构建配置一个字都不用动。第三条，分层可替换。UI 是 UI，数据是数据，中间加一层"数据提供者"，将来换接口、换存储都不至于推倒重来。

这三条约束说白了就是：用最熟的东西，做最快的事，同时给未来留一条不疼的退路。实际跑下来，我认为这个决策是正确的。项目从搭建到核心功能跑通，只用了不到四个工作日，其中一半时间花在业务逻辑梳理上，技术本身的阻力很小。

2.2 目录结构按功能域组织，而不是按文件类型

"rea"的工程目录我要求按功能域划分，而不是按组件、页面、工具这种类型堆在一起。

rea/ mock/ records.js src/ features/ records/ components/ pages/ services/ shared/ components/ utils/ store/ index.js scripts/ dev.sh build.sh

按功能域组织的最大好处是：改需求时只进一个目录，不会把无关文件卷进来。比如"records"这个业务域的所有东西，表单、列表、详情、筛选相关代码都在一起，换人接手时打开一个目录就够了。按类型组织的方案，往往一个需求要改四个目录，跨域牵连特别多。

分享一个细节，services 目录里不直接写接口请求，而是封装业务方法。比如 getRecords(params)、createRecord(data)、exportRecords(params)。页面只跟这些方法打交道，不关心它们在背后是请求了远程接口还是读的本地 mock。这个习惯帮了大忙，后期联调时页面代码几乎没动。

2.3 先用本地数据层把业务跑通，再接真实接口

为了让前端不被后端开发阻塞，"rea"在第一天就搭了一个本地 mock 层。方法很简单，mock 目录下放一份模拟返回数据，数据提供者根据环境开关决定走 mock 还是走真实接口。

// mock/records.js export const mockRecords = [ { id: 'r-001', title: '年度预算表', source: '财务', owner: '张敏', status: 'done', createdAt: '2024-03-18' }, { id: 'r-002', title: '项目周报', source: '研发', owner: '李维', status: 'processing', createdAt: '2024-03-17' }, { id: 'r-003', title: '客诉汇总', source: '客服', owner: '王雨', status: 'todo', createdAt: '2024-03-16' }, ];

为什么非要加这一步？因为很多前端项目死磕在联调阶段，要么等接口等到天荒地老，要么接口一返回就想改数据结构。先把本地数据跑通，页面的正常态、空态、加载态、错误态都能提前调一遍，等到联调时只需要验证字段映射是否正确，不用再分心处理 UI 问题。

这里有一个我踩过的坑：mock 数据不要写得太完美。一定得在测试用例里放几笔异常数据，比如字段缺失的记录、超长文本、空字符串状态值。你猜到了，这些就是后续联调最容易出问题的地方，提前在 mock 里暴露出来，比上线前才发现要好得多。

3. 核心交互与数据流：几十行 store 足够管好一个小型应用

3.1 极简 store 的实现思路与适用边界

"rea"规模很小，所以状态管理我完全没有考虑重型方案，直接写了一个几十行的极简 store。

// src/store/index.js const state = { records: [], filter: { keyword: '', status: '', dateRange: null, }, loading: false, }; const listeners = []; export function getState() { return state; } export function setState(partial) { Object.assign(state, partial); listeners.forEach((fn) => fn(state)); } export function subscribe(fn) { listeners.push(fn); return () => { const idx = listeners.indexOf(fn); if (idx > -1) listeners.splice(idx, 1); }; }

它的核心就是发布订阅模式：setState 更新数据并通知所有订阅者，页面通过 subscribe 监听变化。用起来很直白，没有任何魔法。为什么不用重型状态管理？因为"rea"是单页应用、状态层级浅、没有跨页面协同编辑，重型方案在这里纯属负担。新同事看这份代码，一分钟就能看懂，不需要读一大篇文档。

我并不是否定重型方案，它确实适合复杂场景。但得先判断项目规模，小项目强行引入一套复杂的架构，维护成本比收益大得多。适用边界我通常这样判断：如果项目里共享状态超过三个模块、多角色权限、有复杂缓存或回滚需求，再考虑升级方案；否则一个几十行的 store 完全够用。

3.2 表单、列表、筛选如何串成闭环

有了 store，核心交互就变成了"数据怎么流"的问题。"rea"的结构是单向的：表单提交之后，调用服务方法，拿到返回结果后 setState 更新 records，列表组件因为 subscribe 了 store，自动渲染新数据。

筛选的逻辑稍微绕一点。我做了两件事：第一，筛选条件也放进 store 的 filter 里；第二，列表展示的数据不是直接读 store.records，而是通过一个计算函数 deriveVisibleRecords()，它同时读取 records 和 filter，然后进行过滤和排序。

这样做的收益是：筛选条件变了，只要 setState 更新 filter，列表自然跟着变，不需要手动再调一次查询接口。当数据量不大时，前端过滤体验比每次请求后端都要快，因为不用等网络往返。

表单校验这块我也踩出了一些心得。校验规则放在提交前统一执行，校验失败的字段用统一的错误文案格式提示。错误提示要指出具体字段，而不是笼统地说"提交失败"。我还顺手加了两个额外校验：名称不能只填空格，状态值必须在枚举列表里。这些看似小事，实际是后面边界输入问题的第一道防线。

3.3 本地数据与真实接口的平滑切换

本地 mock 与真实接口的切换，我设计了一个 dataProvider 来做统一出口。

// src/services/dataProvider.js const useMock = import.meta.env.VITE_USE_MOCK === 'true'; export async function fetchRecords(params) { if (useMock) return mockFetchRecords(params); return httpFetch('/api/records', params); } export async function createRecord(data) { if (useMock) return mockCreateRecord(data); return httpFetch('/api/records', { method: 'POST', data }); }

环境开关放在构建时而不是运行时，用环境变量注入。构建时固定下来之后，每个环境跑什么模式是可预期的，不会出现在界面上手动切来切去导致环境不一致的问题。联调开始之后，把测试环境的 VITE_USE_MOCK 置为 false，本地开发保持 true，互不干扰。

切换过程中很容易忽略一个细节：mock 的返回结构要跟真实接口保持一致。如果 mock 返回 { code: 0, data: [...] }，真实接口返回一个裸数组，联调当天肯定翻天。所以我在 mock 层也套了同一套包装结构，这在后面联调时省了大量时间。

4. 实测踩坑记录：状态不同步、边界输入和联调字段变动

4.1 详情页显示旧数据：一次状态不同步的完整排查

这个 bug 是测试阶段第一个被报出来的：列表里先打开一条 A 记录，关闭，把筛选条件换成另一组，再打开一条 B 记录，结果详情页显示的仍旧是 A 的数据。第一次复现我以为是缓存问题，清缓存没用，重启没用，最后只能走代码排查。

排查的链路我完整走了一遍。先加日志，在打开详情页的方法里打印出传入的记录 id 和详情页实际渲染的字段值。日志显示，页面拿到的是 B 的 id，但渲染时读的却是一个名叫 selectedRecord 的独立状态，它的值还停留在上一次的 A。问题一下就清楚了：selectedRecord 在打开详情页时被赋值了一份"记录快照"，但这个快照不会随筛选结果变化而更新，所以每次打开详情页，它都拿的是缓存下来的旧对象。

修复方案也很简单：详情页不存快照对象，只存 currentRecordId，渲染前从 store.records 里通过 id 实时查找最新记录。这样只要 store 里的 records 是对的，详情页永远不会显示旧数据。

注意：派生数据不要作为独立状态保存。凡是能通过现有数据计算出来的内容，一律实时计算，否则容易出现"两个源数据不一致"的经典问题。

这次排查给我的教训很深：不要迷信缓存，不要怀疑框架，先检查数据来源是不是唯一的。

4.2 空字符串与超长文本：边界输入的两个典型案例

"rea"的边界输入问题是在内部试用时暴露的。第一个案例是空字符串。录入表单的名称字段，用户输入了几个空格，前端校验没拦住，结果列表里出现了一条"未命名记录"。原因很简单，trim 操作没做，空格被当成了合法名称。

修复思路是在接入层统一做归一化。前端校验做一个 trim 和必填检查，数据提供者在写入前再 trim 一遍，双层保险。另外空字符串状态值也不安全，筛选逻辑里 status === '' 和 status === ' ' 会同时触发条件分支，所以我把状态值强制映射为预设枚举，不在枚举范围内的值统一记成 unknown。

第二个案例是超长文本。用户从别处粘贴了一整段带换行、带高亮的富文本到备注字段，列表卡片直接撑破了布局。这个不能简单截断，因为详情页还是要看到完整内容的。我的做法是：存储层保留原始文本不做改动，列表展示层使用统一的截断函数，显示两行省略号即可。

export function clampText(text, max = 60) { const normalized = String(text ?? '').replace(/\s+/g, ' ').trim(); if (normalized.length <= max) return normalized; return normalized.slice(0, max) + '…'; }

这两个案例的共同点是：用户不会按你的规范输入，所以不能靠使用者自觉，必须由接入层把脏数据挡住。

4.3 接口字段说改就改：用映射层挡住页面改动

联调第三天，后端发来一条消息：接口返回字段改了，之前的 title 改成了 name，created_at 改成了 createTime，状态字段从字符串改成了嵌套对象。如果页面代码直接消费接口字段，这基本等于把前端的列表、表单、详情全部翻一遍。

幸好"rea"在服务层做了一层字段映射，我在 dataProvider 里加了 normalizeRecord 函数，接口的数据先进这里统一转换。

function normalizeRecord(raw) { return { id: raw.record_id ?? raw.id, title: raw.name ?? raw.title, source: raw.source_name ?? raw.source, owner: raw.owner_name ?? raw.owner, status: raw.state?.code ?? raw.status, createdAt: raw.create_time ?? raw.created_at ?? raw.createTime, }; }

页面只消费 normalize 之后的标准字段，后端以后怎么改，我只动这一个函数。这次字段变更实际只花了一小时就全部搞定，其中大半时间还是在跟后端确认旧数据的兼容逻辑。

这个经验后来被我用到了所有项目里，不管后端是刚开始定义接口，还是已经相对稳定，前端一律不直接消费原始字段。映射层虽然多写几行代码，但它是缓冲垫，能挡住前后端契约频繁抖动带来的连锁改动。

5. 项目复盘：三条能直接抄走的团队约定

5.1 验收清单与回归清单

"rea"上线前，我列了一份验收清单，不是走形式，而是每一行都能落到具体操作上。

回归清单主要针对踩过的坑：详情页在切换筛选和多次开关后，必须确保显示最新记录；边界输入样例在回归时必须再跑一遍；接口字段映射层修改后，需要跑全量用例防止漏改。

5.2 三条约定：派生数据不落 store、接口字段过映射层、输入边界统一归一化

项目总结会上，我把这次的经验浓缩成了三条约定，不是三条空话，是三条可以直接执行的标准。

第一条，派生数据不落 store。状态里只放原始数据，凡是能通过现有数据计算出来的内容，一律通过函数实时计算。这样从根上避免了数据不同步问题。第二条，接口字段必须过映射层。前端代码禁止直接消费接口原始字段，所有外部数据必须先过 normalize 函数，再进入页面逻辑。第三条，输入边界在接入层统一归一化。空串、非法枚举、超长文本的处理逻辑集中在数据接入处，不散落在页面代码里。

这三条约定后来直接写进了我们小组的工程文档，后续几个小项目都按照这个套路执行。踩坑的人少了，代码 review 的讨论也少了很多。

我在实际带这个项目的过程中最大的体会是：短平快的项目，成败往往不在技术，而在于边界定义得是否清楚、数据流设计得是否干净。技术选型只要守住稳定和熟悉这两条，基本不会出大问题；真正的坑全藏在那些不起眼的状态同步、边界输入和字段变化里。越是时间紧，越要在这些地方多花半小时，因为返工的成本远大于预防的成本。

如果让我再提一个最后的小建议，那就是找一张纸，写下项目里最大的三个风险点，贴在工位上。做完一件事，划掉一个。专注地盯着风险点推进，才能保证短周期项目不崩溃。