摸鱼低代码平台mfish-nocode二次开发入门：读懂微服务单体一体化架构，写出你的第一个自定义模块

• 后端
• 低代码
• 微服务
• AI 应用
• 大模型

摸鱼低代码平台 mfish-nocode 二次开发并不复杂。本文带你从它最有特色的微服务单体一体化架构讲起，用最短的路径看懂"一套代码、两种形态"的设计思路，然后一步步写出你的第一个自定义模块。无论你是刚接手项目的后端新手，还是想在低代码平台上扩展业务功能的开发者，这篇入门教程都能帮你在半小时内跑通二次开发全流程 🚀

🧭 二次开发前，先认清项目骨架

先导入仓库并浏览目录结构，你会发现项目按职责划分得非常干净：

💡 二次开发的 90% 工作集中在mf-business（写业务）和mf-start（选择启动方式），mf-common里的能力拿来用即可。

🏗️ 快速读懂"微服务单体一体化"架构

这是 mfish-nocode 最核心的卖点：同一套代码，既能整体打成单应用跑，又能拆成多个微服务跑。它靠两个"组合注解"实现。

单体形态：一个 @AutoWeb 注解搞定

单实例启动类只有寥寥数行，定义在 MfNoCodeStart.java：

@AutoWeb public class MfNoCodeStart { public static void main(String[] args) { ConfigurableApplicationContext application = SpringApplication.run(MfNoCodeStart.class, args); } }

其中 @AutoWeb 是一个"套餐注解"，一次性装配了三件事：

@SpringBootApplication @AutoSwagger @MapperScan({"cn.com.mfish.**.mapper"}) public @interface AutoWeb { }

• @SpringBootApplication：标准 SpringBoot 启动
• @AutoSwagger：自动注册 Swagger 接口文档
• @MapperScan：扫描所有cn.com.mfish.**.mapper包——这是关键！所以你把新模块的 Mapper 放在约定包路径下，就能被自动识别，无需任何额外配置

单体模式下，所有业务模块（oauth、sys、workflow、demo……）都被 mf-start-boot 的 pom 以依赖形式聚合进一个进程，数据库只需要导入一份 db/mfish_nocode.sql。

微服务形态：换成 @AutoCloud 即可拆分

每个服务都有独立的启动模块，如 MfDemoApplication.java 上标注的是 @AutoCloud：

@AutoFeignClients @AutoWeb public @interface AutoCloud { }

它 =@AutoWeb+@AutoFeignClients。多出来的 Feign 能力用于服务间远程调用，接口定义在 mf-api/ 各模块中（如 mf-sys-api）。

一句话总结架构规律

💡 对新手最友好的地方：先学单体模式。本地方法直调、单库调试，遇到问题好排查；等模块写熟了，再切换到微服务形态几乎零成本。

🧩 抄作业模板：demo 模块的标准分层

mf-business/mf-demo/ 是官方留给你"抄作业"的样板间，以销售订单为例，标准六层结构如下：

mf-demo/ ├── controller/ DemoOrderController.java 接口层 ├── entity/ DemoOrder.java 实体层 ├── mapper/ DemoOrderMapper.java + xml 数据访问层 ├── req/ ReqDemoOrder.java 查询参数对象 └── service/ DemoOrderService + impl 业务逻辑层

打开 DemoOrderController.java，记住这五个"必会五件套"：

1. 统一返回体：Result<T>+PageResult<T>，所有接口都用它包裹
2. 分页参数：ReqPage接收pageNum/pageSize，配合PageHelper.startPage完成分页
3. 权限注解：@RequiresPermissions("demo:demoOrder:query")，与业务代码完全解耦的权限控制
4. 操作日志：@Log(title = "销售订单-添加", operateType = OperateType.INSERT)一行注解自动记日志
5. 接口文档：@Tag+@Operation，Swagger 文档自动生成

Service 层则继承 MyBatis-Plus 的IService<T>，实现类继承ServiceImpl<Mapper, Entity>，单表 CRUD 直接白嫖框架，业务方法里用LambdaQueryWrapper拼条件即可，参考 DemoOrderServiceImpl.java。

✍️ 五步写出你的第一个自定义模块

第一步：新建业务模块

在 mf-business/ 下仿照 mf-demo/pom.xml 创建mf-xxx模块，核心依赖只有几个：

<dependency> <groupId>cn.com.mfish</groupId> <artifactId>mf-common-web</artifactId> <!-- 提供 Result、@AutoWeb 等基础能力 --> </dependency> <dependency> <groupId>cn.com.mfish</groupId> <artifactId>mf-xxx-api</artifactId> <!-- 你自己的 Feign 接口模块（可选） --> </dependency>

然后在mf-business/pom.xml的<modules>中注册新模块。

第二步：选择启动方式

• 单体模式：在 mf-start-boot/pom.xml 中加一行对mf-xxx的依赖，MfNoCodeStart会自动扫描到你的代码 ✅（推荐新手）
• 微服务模式：仿照 mf-start-demo/ 新建mf-start-xxx启动模块，标注@AutoCloud，并在 mf-api/ 下定义 Feign 接口供其他服务调用

第三步：按标准分层写代码

按 demo 模块的五件套照抄骨架即可。包名务必放在cn.com.mfish.xxx.mapper这样的路径下，@AutoWeb的全局@MapperScan才能扫到你的 Mapper。

第四步：接入数据库与菜单权限

1. 为业务表建库表（单体模式直接加到mfish_nocode库）
2. 登录后台（默认账号 admin），在菜单管理中新增菜单
3. 在角色管理中把菜单权限分配给角色，权限标识与@RequiresPermissions中的字符串一一对应

第五步：Swagger 验证接口

启动后访问http://localhost:8888/swagger-ui/index.html，找到你新模块的接口分组，直接在线调试。单体模式启动只需两步：导入 db/mfish_nocode.sql，运行MfNoCodeStart——比任何脚手架都简单。

💡 新手避坑清单

• ❗包路径必须匹配cn.com.mfish.**.mapper，否则 Mapper 扫不到，启动报"无效 namespace"
• ❗权限标识写错会导致接口 403，调试时可先临时去掉@RequiresPermissions
• ❗微服务模式忘了起 Nacos 会注册失败；单体模式则完全不需要 Nacos
• ❗微服务间调用要通过 mf-api/ 中的 Feign 接口，不要直接依赖对方业务模块

📚 小结

mfish-nocode 二次开发的核心就三件事：看懂 @AutoWeb/@AutoCloud 的双形态启动、模仿 mf-demo 的标准分层、按包路径约定让框架自动装配。架构上的"单体微服务一体化"设计，让你先用单体模式快速验证业务，再无痛切换到微服务——学习和实战两不误，这正是"摸鱼式开发"的精髓所在 🐟

更多模块细节与启动说明可查阅 README.md 与 db/README.md。

• 后端
• 低代码
• 微服务
• AI 应用
• 大模型