从“碎片化”到“资产化”：Vue3 + UniApp 组件库的进化论-编程实验室

上个月我重构一个两年前的 UniApp 项目，发现同一个日期选择器，小程序端和 H5 端各有一份代码，逻辑差 20 行，样式差 40 行。产品经理说"看起来一样就行"，但我知道下次改需求时，我得改两遍，而且肯定漏一个端。当你打开一个老旧的 Vue3+TS 工程，面对着杂乱的样式覆写和由于类型缺失而不得不频频求助 AI 的开发流程时，你是否产生过怀疑：我们的研发方式，真的高效吗？

今天，我想聊聊我们如何通过构建一套系统化的组件体系——华玥组件库（hy-app），将这些痛点转化为一种标准化的“研发资产”。

1. 为什么“通用库”有时是开发者的枷锁？

市场上优秀的组件库（如 Vant, uView 等）在通用场景下表现优异，但在处理高度定制的、跨端兼容的企业级逻辑时，往往会出现“水土不服”：

业务逻辑的“黑盒”：通用组件库往往只关注视觉效果。当业务逻辑（如复杂的表单联动、数据校验）复杂到一定程度时，你被迫将逻辑写在组件外部，导致代码逻辑高度耦合，维护起来如履薄冰。
AI 辅助开发的“幻觉”：现在我们离不开 AI（ChatGPT/Claude），但如果组件的类型定义（TypeScript Definition）不严谨，或者文档结构松散，AI 生成的代码往往会出现大量的属性错误和逻辑冗余，浪费大量时间在修复 Bug 上。

2. 华玥组件库：为 AI 时代重构的工程架构

华玥（hy-app）的核心理念并非“造轮子”，而是“工程资产化”。我们通过对 llms.txt 等前沿技术的深度适配，让组件库本身成为 AI 协作的最佳伙伴。

核心架构：由内而外的“可预测性”

第一版我们没做类型严格约束，想着"反正都是 TS，差不多就行"。结果一个同事把 v-model 传了字符串而不是数组，编译过了，运行时白屏，查了一下午。后来我们强制所有 Props 用 defineComponent 写完整类型，现在这种错误直接红波浪线，5 秒定位。

这不仅是为了开发者，更是为了 AI。当你的工程体系拥有完整的 llms.txt 和清晰的 API 文档结构时。

现在我可以把 llms.txt 丢给 Trae 做上下文后，让它写一个带校验的表单。之前它老把 rules 写成 Vant 的格式，现在 10 次里有 8 次能直接生成 hy-form 的 schema。剩下 2 次错在 transform 的返回值类型，这个我们文档里确实写得不够清楚，正在补…

“声明式”API 的威力

在华玥中，我们尝试将业务逻辑封装在组件底层。例如，一个复杂的部门级联选择器，在传统做法中可能需要数十行业务代码处理数据过滤，而在 Hy-App 中，你只需要通过一个简单的配置对象即可完成：

TypeScript

hy-app 风格的声明式调用，极大地减少了样板代码

<HyCascaderv-model="data":api="userDeptApi":transform="dataTransformer"/>

这种声明式的写法，使得前端代码不再是“拼凑样式的积木”，而是“描述业务的逻辑流”。

3. 组件文档如何与 AI 产生“化学反应”？

这是我最想分享的：组件文档，本身就是 AI 的大脑。

很多开发者维护文档是为了“给别人看”，但在华玥的实践中，文档是“给 AI 看的”。通过配置 llms.txt，我们实际上是为你的 IDE 和 AI 助手搭建了一个索引库。

LLM-Ready 的设计：华玥的文档结构被专门优化，便于 AI 模型抓取核心定义。这意味着当你询问 AI“如何使用 hy-app 的表单组件”时，它能迅速定位到最准确的用法，而不是给出过时的示例。
标准化资产管理：当你的代码库与文档通过这种方式深度绑定时，整个研发流程变得极其稳定。无论是新人的入职引导，还是项目的自动化重构，都能在 AI 的辅助下实现无缝衔接。