微信小程序开发规范全指南,从目录结构到代码风格详解

文章分类:新闻资讯 发布时间:2026-11-21 原文作者:小程序开发 阅读( )

微信小程序开发规范全指南,从目录结构到代码风格详解

微信小程序的目录结构,很多人一开始不太在意,觉得能跑就行。但项目稍微大一点,问题就来了:页面找不到、组件重复写、工具函数到处复制。一个清晰的目录结构,本质上是在给未来的自己省时间。通常我会把项目根目录分成几个固定区域:pages放主包页面,每个页面一个文件夹,里面至少包含四个文件(.js、.json、.wxml、.wxss),文件名和文件夹名保持一致。subpackages放分包,按业务模块划分,比如subpackages/order、subpackages/user。components放公共组件,每个组件也独立成文件夹。utils放工具函数,按功能拆成独立文件,比如request.js、format.js、storage.js。static或assets放图片和字体资源。config放环境配置和常量。这样分下来,任何人接手项目,五分钟就能摸清代码在哪。

页面内部的代码组织同样有讲究。一个Page的.js文件,我习惯按固定顺序写:先写data,再写生命周期函数(onLoad、onShow、onReady等),然后是自定义方法,最后是事件处理函数。事件处理函数的命名要能看出来它对应哪个元素,比如handleSubmitTap、handleInputChange,不要用click1、btnTap这种名字。wxml里的绑定也要跟方法名对得上,这样调试的时候一眼就能定位。另外,data里不要塞太多东西,只放跟渲染相关的数据。那些不需要驱动视图的变量,直接挂在this上或者用模块级变量存,减少setData的负担。

说到setData,这是小程序性能最容易踩坑的地方。很多人习惯把整个对象重新set一遍,比如this.setData({list: newList}),如果list很大,每次更新都全量传,视图层压力很大。规范的做法是只set变化的字段,用数据路径的方式,比如this.setData({'list[0].name': '新名字'})。另外,频繁setData要合并,能一次set完的不要分三次。还有一点,setData的回调不要写太多逻辑,它只是视图更新完成的信号,不是用来做业务处理的。把这些细节写进团队规范里,能避免很多“页面卡顿但找不到原因”的情况。

代码风格这块,小程序原生开发没有强制eslint配置,但团队内部一定要统一。我建议直接上eslint加prettier,配置一份共享的.eslintrc,所有人继承同一套规则。具体到写法上,缩进统一用两个空格,字符串统一用单引号,语句末尾必须带分号——这些看起来是小事,但混着写的时候,diff里全是格式变动,review代码很痛苦。变量命名用驼峰,常量全大写加下划线,组件名用短横线连接。函数尽量保持单一职责,一个函数超过50行就该考虑拆了。注释不要写“这是什么”,要写“为什么这样”。比如// 因为接口返回的status字段有四种状态,这里只处理已支付和已发货,剩下的走默认逻辑。

组件化是小程序规范里绕不开的话题。什么时候该抽组件?我的判断标准是:同一段wxml结构在三个以上地方出现,或者一个模块的交互逻辑超过100行,就抽。抽出来的组件要遵守“输入输出明确”的原则:properties定义清楚类型和默认值,events定义清楚触发时机和参数。不要在组件内部直接调接口或者操作全局状态,那是页面该做的事。组件的wxss要加样式隔离,默认的isolated就够了,除非确实需要继承外部样式。还有,组件命名要加前缀,比如my-、app-,避免和原生组件或第三方库冲突。

接口请求和状态管理也需要规范。请求统一走封装的request函数,不要在每个页面里直接写wx.request。封装层要处理:baseURL拼接、token注入、loading显示隐藏、错误码统一处理、超时重试。状态管理方面,小项目用globalData就够了,但要在app.js里集中管理,不要到处this.globalData = xxx。中大型项目建议上mobx-miniprogram或者westore,把状态变更逻辑收拢到store里。页面只负责展示和触发action,不直接改store。这样测试和调试都方便,也能避免多个页面同时修改同一份数据导致的诡异bug。

最后说版本管理和协作规范。小程序开发者工具自带git,但很多人只把它当上传工具用。团队协作至少要有两个分支:master和develop。功能开发在feature/xxx分支上,提测前合并到develop,上线后合并到master并打tag。每次提交前跑一遍eslint,不要提交带console.log的代码。commit message写清楚做了什么,不要只写“修改”“更新”。另外,project.config.json里的appid不要写死,用环境变量或者单独的配置文件,避免不同开发者互相覆盖。把这些规范写进项目的README里,新人才知道该怎么跟。

回到标题说的“从目录结构到代码风格”,其实规范的核心就一句话:让代码可预测。目录结构可预测,就知道文件在哪;命名可预测,就知道函数干什么;数据流可预测,就知道改哪里会影响哪里。小程序开发本身不难,难的是多人协作时保持一致性。一套好的规范不是限制,是减少沟通成本的工具。花半天时间把规范定下来,后面能省掉无数次的“这个地方为什么这么写”的讨论。

原文来自:小程序开发