微信小程序开发规范指南，让代码整洁高效又易维护

写代码这事儿，跟收拾屋子是一个道理。刚搬进新家时整整齐齐，住上三个月，茶几上堆满外卖盒，沙发上挂着没叠的衣服，抽屉里塞满充电线。小程序项目也一样，刚启动时大家热情高涨，代码写得漂漂亮亮；等迭代到第三个版本，页面文件堆了一堆，全局变量满天飞，改个按钮颜色都得翻三四个文件。这时候你才会发现，是否有一套开发规范，直接决定了你是每天在屎山上修修补补，还是能从容地加新功能。我见过太多团队，前期图省事不搞规范，后期改一个 bug 就会引出三个新 bug，项目烂尾。所以今天这篇指南，就是想把那些血泪教训总结出来，让你少走弯路。

先说项目结构，这是代码的骨架。很多人拿到小程序就开干，所有页面堆在 pages 文件夹里，所有组件塞在 components 文件夹里，然后每个页面里又混着网络请求、数据处理、视图渲染。等页面多了，你根本分不清哪个文件是干嘛的。我的建议是，按照业务模块来划分文件夹。比如一个电商小程序，可以拆成 home、product、cart、order、user 这几个模块，每个模块下面再放 pages、components、utils 这些子文件夹。这样做的好处是，改购物车逻辑时，你只需要钻进 cart 文件夹，不用在其他地方瞎翻。另外，全局配置和工具函数一定要单独拎出来，比如 app.js 里只放生命周期和全局数据，api 文件夹放所有网络请求的封装，utils 文件夹放日期格式化、正则校验这类通用函数。结构清晰了，新人接手也能很快找到方向。

接下来是命名规范，这是代码的脸面。你见过那种变量名叫 a、b、c，函数名叫 doSomething、handleClick 的代码吗？看着就头大。在微信小程序里，命名要遵循几个原则。文件名用短横线连接，比如 product-list.wxml、order-detail.js，这样在微信开发者工具里一眼就能看出是哪个页面。变量名用驼峰，普通变量用名词，布尔值用 is 或 has 开头，比如 isShowLoading、hasMoreData。函数名用动词开头，比如 getUserInfo、submitOrder、handleTap。组件名用大写字母开头，比如 ProductCard、SearchBar。不要小看这些细节，当你需要在几十个文件里找一个功能时，好的命名能让你用搜索功能一秒定位。我见过最离谱的命名，一个变量叫 data，一个叫 data1，还有一个叫 data2，简直是在考验队友的阅读理解能力。

再说说组件化开发，这是代码复用的核心。很多新手写小程序，习惯把整个页面写在一个 wxml 文件里，结果一个文件上千行，改个样式还得全局搜索。正确的做法是，把页面拆成多个独立组件。比如一个商品详情页，可以拆成商品轮播图组件、商品信息组件、规格选择组件、评价列表组件。每个组件只负责自己的数据和样式，页面本身只做组装和状态管理。这样做的好处太多了：组件可以复用，比如商品卡片组件可以在首页、搜索结果页、推荐页同时使用；组件可以独立测试，改轮播图样式不会影响其他部分；组件可以按需加载，提升页面性能。微信小程序对组件的支持已经很成熟，用 Component 构造器创建组件，用 properties 接收外部数据，用 observers 监听数据变化，这套机制用好了，代码质量能上一个台阶。

样式管理这块，很多人容易翻车。微信小程序不支持 CSS 预处理器，但我们可以用一些技巧保持样式整洁。所有颜色、字号、间距这些常用值，都定义在 app.wxss 里作为全局变量，用 CSS 自定义属性来管理，比如 --primary-color: #07c160; --font-size-base: 14px;。然后在各组件里引用这些变量，这样想改主题色时，只需改一个地方。样式命名采用 BEM 规范，比如 .product-card__title--active，虽然看着长，但能避免样式冲突。还有一个小技巧：每个组件单独建一个 wxss 文件，用 @import 引入公共样式，但不要引入太多，否则会导致样式文件过大。尽量少用 !important，这东西就像代码里的地雷，一旦用了，后面的人只能跟着埋雷。

数据管理和通信是高级玩法，也是项目变大必经之路。小程序里，页面之间传参可以用 navigateTo 的 url 参数，但参数多了就乱套。组件之间传参可以用 triggerEvent 向上传，用 properties 向下传。但如果你发现数据在多个页面和组件之间来回传，那就要考虑引入全局状态管理。微信小程序自带的 getApp() 可以获取全局实例，但用不好容易造成数据污染。我推荐使用 mobx-miniprogram，或者自己写一个简单的 store，把用户信息、购物车数据、配置信息这些全局共享的数据集中管理。每个组件只从 store 里取自己需要的数据，修改数据通过 action 触发，这样数据流向清晰，调试也方便。记住一个原则：组件内部的数据自己管，组件之间的数据通过事件传递，全局数据用 store 管理。

代码质量和性能优化也不能忽视。微信小程序对代码大小有限制，主包不能超过 2 M，所以一定要做代码分包。按业务模块分包，把首屏不用的页面放到分包里，比如用户协议、帮助中心这些不常用的页面。另外，setData 是性能杀手，每次调用都会引起页面重新渲染，所以要控制 setData 的频率和数据量。只更新变化的部分，不要把整个 data 都传进去。列表渲染时加上 key，用 wx:key 而不是直接写索引，这样能提升渲染效率。还有图片懒加载、防抖节流等常规操作，该用就用。养成写注释的习惯，但不是每个变量都写注释，而是标注逻辑复杂的地方，例如“这里用递归处理多级评论，注意防止栈溢出”。

说到底，开发规范不是为了束缚你，而是让代码有生命力。一套好的规范，能让新人在三天内上手，能让老手在改 bug 时少掉头发，能让项目在迭代一年后依然健壮。我见过最崩溃的场景，是凌晨三点，团队四个人在群里争论变量名到底该叫 userName 还是 user_name。也见过最爽的场景，是接手一个老项目，打开代码发现结构清晰、命名规范、注释到位，半天就理清了所有逻辑。所以，别嫌麻烦，从下一个项目开始，和团队定好规范，写在文档里，挂在墙上，形成习惯。代码整洁了，心情也好了，工作效率自然上来了。记住，规范不是负担，而是你未来节省时间的杠杆。