1. 从脚手架到业务系统ng-alain 项目改造的整体思路拆解很多团队用 ng-alain 起项目第一步都是ng new或者直接拉官方 starter跑起来一看登录页、侧边栏、仪表盘全都齐了感觉省了半个月工作量。但真正开始接业务需求时问题就来了默认的目录结构是按框架作者的理解划分的默认的路由是懒加载但粒度很粗默认的权限是写死的 mock默认的布局是全局统一的。你如果直接在这个基础上堆业务代码三个月后项目就会变成一锅粥——改一个菜单要动五个文件加一个页面要复制三处配置。所以“项目改造”这件事本质上不是把 ng-alain 换掉而是把它从一个演示型脚手架改造成一个可持续演进的业务系统底座。我在几个中后台项目里反复做过这件事踩过的坑足够写一篇长文。这一篇就围绕改造这件事把思路、目录、路由、权限、布局、Mock、构建这几块拆开讲透。1.1 改造前先想清楚ng-alain 给了什么缺什么ng-alain 的定位很明确它是基于 Angular 和 NG-ZORRO 的一套企业级中后台前端解决方案。它给你的东西包括一套完整的布局组件侧边栏、顶栏、标签页、页脚、一套基于 ACL 的权限指令、一套基于 AlainTheme 的配置体系、一套基于 Mock 的本地数据模拟、以及一堆开箱即用的业务组件ST 表格、SF 表单、SV 查看器、Chart 图表等。它缺的东西同样明确它不知道你的业务边界在哪里。默认的routes是平铺的默认的app目录是扁平的默认的shared是空的默认的core里只有框架自己的东西。你要做的改造就是把这些“空白”填成你团队能长期维护的结构。我一般把改造分成六个维度来看后面每一节展开一个改造维度默认状态目标状态优先级目录结构扁平、按类型分分层、按业务域分高路由组织单文件平铺模块化、懒加载高权限体系Mock 写死接口驱动、按钮级高布局配置全局统一按路由切换中Mock 数据静态 JSON动态、可拦截中构建部署默认配置多环境、按需中这张表不是拍脑袋来的是我在三个项目里反复调整后沉淀下来的顺序。目录和路由必须先动因为后面所有改造都依赖它们权限和布局可以并行Mock 和构建放到最后因为它们不影响业务代码的组织。1.2 为什么改造要“渐进式”而不是“推倒重来”我见过有团队嫌 ng-alain 默认结构乱直接删掉app目录重新搭。结果呢框架自带的布局组件、ACL 指令、主题服务全都要重新接一遍两周过去了还在调侧边栏的折叠动画。这是典型的“为了重构而重构”。正确的做法是渐进式改造保留框架的核心能力只替换业务层的组织方式。具体来说框架的delon/*系列包、AlainThemeModule、LayoutModule这些不要动你要动的是src/app下的业务代码组织、src/environments下的环境配置、src/app/routes下的路由定义。提示改造前一定要先git commit一次把官方 starter 的原始状态存下来。改造过程中如果发现某个框架能力被自己改坏了可以随时 diff 回去看原始实现。渐进式改造还有一个好处每一步都可以跑起来验证。你改完目录结构ng serve能跑改完路由页面能跳改完权限登录能过。而不是改了两周才发现某个环节对不上回头找问题像大海捞针。2. 目录结构改造从“按类型分”到“按业务域分”这是改造的第一步也是最容易被低估的一步。很多人觉得目录结构就是文件夹怎么摆无所谓。但目录结构决定了你找代码的速度、决定了模块之间的依赖关系、决定了新人上手的时间。一个按业务域划分的目录新人进来三天就能知道“订单相关的代码都在orders目录下”一个按类型划分的目录新人要找订单列表页得在pages、services、models、components四个目录里翻。2.1 默认目录的问题在哪里ng-alain 默认的src/app大概长这样src/app/ ├── core/ # 核心服务、拦截器、守卫 ├── shared/ # 共享模块、指令、管道 ├── routes/ # 路由配置 ├── layout/ # 布局组件 ├── app.module.ts └── app.component.ts业务页面通常放在routes下面按路由路径建文件夹。问题在于当业务模块超过十个routes目录会变成一个巨大的平铺列表而且每个业务模块的组件、服务、模型散落在不同地方。比如订单模块列表页在routes/orders/list详情页在routes/orders/detail订单服务在core/services/order.service.ts订单模型在shared/models/order.model.ts。改一个订单字段要动四个目录。2.2 改造后的目录结构我的做法是把业务代码收敛到modules目录下按业务域划分src/app/ ├── core/ # 全局单例服务、拦截器、守卫、常量 │ ├── interceptors/ │ ├── guards/ │ ├── services/ │ └── constants/ ├── shared/ # 无状态共享组件、指令、管道 │ ├── components/ │ ├── directives/ │ ├── pipes/ │ └── shared.module.ts ├── layout/ # 布局保持框架默认 ├── modules/ # 业务模块核心改造点 │ ├── dashboard/ │ │ ├── components/ │ │ ├── pages/ │ │ ├── services/ │ │ ├── models/ │ │ ├── dashboard-routing.module.ts │ │ └── dashboard.module.ts │ ├── orders/ │ │ ├── components/ │ │ ├── pages/ │ │ ├── services/ │ │ ├── models/ │ │ ├── orders-routing.module.ts │ │ └── orders.module.ts │ └── system/ │ ├── users/ │ ├── roles/ │ └── system.module.ts ├── app.module.ts └── app.component.ts这个结构的关键在于每个业务模块是一个自包含的单元。订单模块的所有代码都在modules/orders下包括它的路由、服务、模型、组件。模块之间通过shared和core通信不允许直接互相引用。这样做的好处是将来如果要把订单模块拆成独立应用直接把这个目录搬走就行。2.3 目录改造的实操步骤改造不是简单地把文件挪位置因为挪完之后 import 路径全变了。我的做法是分三步走第一步先建好新目录骨架把modules目录建出来但先不挪文件。第二步逐个模块迁移每迁移一个模块就用 IDE 的“移动文件并更新引用”功能VS Code 和 WebStorm 都支持确保 import 路径自动更新。第三步全部迁移完后全局搜索一遍routes/的引用把残留的路径改掉。这里有个细节要注意Angular 的路径别名。在tsconfig.json里配置paths可以让 import 路径更短更清晰{ compilerOptions: { paths: { core/*: [src/app/core/*], shared/*: [src/app/shared/*], modules/*: [src/app/modules/*] } } }配好之后原来写import { OrderService } from ../../../core/services/order.service的地方可以改成import { OrderService } from core/services/order.service。路径短了重构时也不容易出错。注意路径别名改完后要同步检查angular.json里的tsConfig配置确保构建时也能解析。另外如果用了 Jest 或 Karma 做测试测试配置里的moduleNameMapper也要同步更新否则测试会报找不到模块。2.4 目录改造的常见坑我踩过最深的一个坑是循环依赖。把业务代码收敛到modules后很容易出现orders模块引用users模块的服务users模块又引用orders模块的模型形成循环。Angular 在编译时不一定报错但运行时会出现undefined的诡异问题。避免循环依赖的原则很简单业务模块之间不直接引用需要共享的东西下沉到shared或core。如果两个模块确实需要通信用事件总线或者状态管理比如 NGXS、Akita来解耦。我在一个项目里就是因为orders和inventory互相引用排查了一整天才定位到问题最后把共享的库存模型下沉到shared/models才解决。3. 路由改造从平铺到模块化懒加载路由是 ng-alain 项目改造里最需要动脑子的部分。默认的路由配置通常是一个大文件所有路由平铺在一起懒加载粒度很粗。业务一多这个文件会膨胀到几百行改一个路由要小心翼翼怕影响别的。3.1 默认路由的问题ng-alain starter 的app-routing.module.ts大概是这样const routes: Routes [ { path: , redirectTo: dashboard, pathMatch: full }, { path: dashboard, component: DashboardComponent }, { path: orders, component: OrdersComponent }, { path: orders/:id, component: OrderDetailComponent }, // ... 几十个路由 ];问题有三个一是所有路由都在一个文件里二是组件都是直接 import 的没有懒加载三是路由和菜单是两套配置改一个要同步改另一个。3.2 模块化路由改造方案改造后的路由应该按业务模块拆分每个模块有自己的路由文件主路由只负责加载模块// app-routing.module.ts const routes: Routes [ { path: , redirectTo: dashboard, pathMatch: full }, { path: dashboard, loadChildren: () import(./modules/dashboard/dashboard.module).then(m m.DashboardModule) }, { path: orders, loadChildren: () import(./modules/orders/orders.module).then(m m.OrdersModule) }, { path: system, loadChildren: () import(./modules/system/system.module).then(m m.SystemModule) } ];每个业务模块的路由文件// modules/orders/orders-routing.module.ts const routes: Routes [ { path: , component: OrderListComponent, data: { title: 订单列表, reuse: true } }, { path: detail/:id, component: OrderDetailComponent, data: { title: 订单详情 } } ];这样做的好处是路由和模块绑定模块和业务域绑定。改订单路由只动orders-routing.module.ts不会影响别的模块。而且loadChildren实现了真正的懒加载首屏只加载 dashboard 模块订单模块在用户点击菜单时才加载。3.3 路由与菜单的联动ng-alain 的菜单是通过MenuService配置的默认和路由是分开的。改造时我建议把菜单配置也下沉到各业务模块通过一个统一的接口注册。具体做法是在core里定义一个MenuProvider接口每个业务模块实现这个接口在模块构造函数里把自己的菜单注册进去。// core/services/menu-provider.ts export interface MenuProvider { registerMenus(menuService: MenuService): void; } // modules/orders/orders.module.ts NgModule({...}) export class OrdersModule implements MenuProvider { constructor(private menuService: MenuService) { this.registerMenus(menuService); } registerMenus(menuService: MenuService) { menuService.add([ { text: 订单管理, link: /orders, icon: shopping-cart, children: [ { text: 订单列表, link: /orders }, { text: 订单统计, link: /orders/stats } ] } ]); } }这样菜单和路由就在同一个模块里改路由时顺手就把菜单改了不会漏。3.4 路由复用的配置ng-alain 支持路由复用Tab 标签页但默认是全局开启的。改造时我建议按路由粒度控制因为不是所有页面都适合复用。比如列表页适合复用用户切来切去不想丢筛选条件详情页不适合复用每次打开都应该是新数据。控制方式是在路由data里加reuse标记{ path: , component: OrderListComponent, data: { reuse: true } }, { path: detail/:id, component: OrderDetailComponent, data: { reuse: false } }然后在RouteReuseStrategy里读取这个标记决定是否复用。这个细节很多教程不讲但实际项目里非常有用不然用户打开十个订单详情标签页会爆炸。4. 权限体系改造从 Mock 到接口驱动权限是中后台系统的核心ng-alain 自带的 ACL 能力其实够用但默认配置是 Mock 的需要改造成接口驱动。4.1 ng-alain 的 ACL 能力拆解ng-alain 的权限体系分两层角色Role和权限点Ability。角色是粗粒度的比如admin、user权限点是细粒度的比如order:create、order:delete。框架提供了ACLService来管理提供了acl指令来控制按钮显示。默认的ACLService是在app.module.ts里用ACLTypeEnum配置的数据是写死的。改造的核心就是把这个写死的数据换成登录后从接口拉取。4.2 接口驱动的权限改造改造步骤分四步第一步登录成功后调用权限接口拿到当前用户的角色和权限点列表。第二步把权限数据存到ACLService里。第三步在路由守卫里校验角色没权限的路由直接跳 403。第四步在按钮上用acl指令控制显示。// core/services/auth.service.ts login(credentials: LoginParams): ObservableUser { return this.http.postLoginResult(/api/auth/login, credentials).pipe( switchMap(result { this.tokenService.set(result.token); return this.http.getPermissionResult(/api/auth/permissions); }), tap(permissions { this.aclService.setRole(permissions.roles); this.aclService.setAbility(permissions.abilities); }) ); }路由守卫// core/guards/acl.guard.ts canActivate(route: ActivatedRouteSnapshot): boolean { const requiredRole route.data[role]; if (!requiredRole) return true; if (this.aclService.hasRole(requiredRole)) return true; this.router.navigateByUrl(/403); return false; }按钮控制button nz-button *aclorder:create (click)create()新建订单/button button nz-button *aclorder:delete (click)remove()删除/button4.3 权限改造的注意事项这里有几个坑我踩过值得单独说。第一个坑是权限数据的缓存。如果每次路由跳转都去拉权限接口性能会很差。我的做法是登录时拉一次存到localStorage或内存里刷新页面时从缓存读同时后台异步刷新。但要注意缓存过期问题token 过期时权限缓存也要清掉。第二个坑是按钮级权限的粒度。有些团队把权限点设计得太细比如order:list:export:excel结果权限点几百个维护成本极高。我的经验是权限点控制在“操作级别”比如order:export具体导出什么格式在前端判断不单独设权限点。第三个坑是路由守卫的顺序。Angular 的守卫执行顺序是canLoad→canActivate→canActivateChild。如果用了懒加载canLoad里做权限校验可以避免无权限的模块被加载性能更好。但canLoad里拿不到ActivatedRouteSnapshot的完整数据需要额外处理。提示权限改造完成后一定要用不同角色的账号完整测一遍。我见过因为守卫写错普通用户能访问管理员页面的情况这种问题上线后很致命。5. 布局与主题改造按路由切换布局ng-alain 默认只有一套布局侧边栏 顶栏 标签页但实际项目里往往需要多套。比如登录页不需要侧边栏大屏展示页需要全屏移动端需要不同的布局。改造布局的关键是让布局跟着路由走。5.1 布局切换的实现方式ng-alain 的LayoutComponent支持通过LayoutService动态切换。我的做法是在路由data里标记布局类型然后在app.component.ts里监听路由变化切换布局。// app.component.ts constructor(private router: Router, private layoutService: LayoutService) { this.router.events.pipe( filter(e e instanceof NavigationEnd) ).subscribe(() { const route this.router.routerState.root.firstChild; const layout route?.snapshot.data[layout] || default; this.layoutService.setLayout(layout); }); }路由配置{ path: login, component: LoginComponent, data: { layout: blank } }, { path: dashboard, component: DashboardComponent, data: { layout: default } }, { path: screen, component: ScreenComponent, data: { layout: fullscreen } }5.2 主题色的动态切换ng-alain 支持主题色切换但默认是全局的。改造时我建议把主题配置也做成可持久化的用户选了主题色刷新后还能保持。实现方式是在AlainThemeConfig里读取localStorage的值切换时写回。// core/services/theme.service.ts setTheme(color: string) { this.alainThemeConfig.setPrimaryColor(color); localStorage.setItem(theme-color, color); } initTheme() { const color localStorage.getItem(theme-color) || #1890ff; this.alainThemeConfig.setPrimaryColor(color); }5.3 布局改造的实操心得布局改造最容易出问题的地方是响应式。ng-alain 的侧边栏在移动端会自动折叠但如果自定义了布局这个行为可能失效。我的做法是保留框架的响应式逻辑只改视觉样式不动交互逻辑。另一个心得是标签页的关闭策略。默认标签页可以关闭任意页面但首页通常不允许关闭。改造时可以在路由data里加closable: false标记然后在标签页组件里读取这个标记控制关闭按钮的显示。6. Mock 与构建改造让开发和部署更顺滑Mock 和构建是改造的收尾工作但同样重要。Mock 决定了前后端联调前的开发效率构建决定了部署的灵活性。6.1 Mock 数据的动态化改造ng-alain 默认的 Mock 是静态 JSON每个接口一个文件。改造时我建议把 Mock 数据做成动态生成的比如列表接口根据查询参数返回不同的数据分页接口根据页码返回对应的数据。// mock/orders.ts export const ORDERS Array.from({ length: 100 }).map((_, i) ({ id: i 1, orderNo: ORD${String(i 1).padStart(6, 0)}, status: [pending, paid, shipped, completed][i % 4], amount: Math.round(Math.random() * 10000) / 100, createdAt: new Date(Date.now() - i * 86400000).toISOString() })); export default { GET /api/orders: (req: Request, res: Response) { const page Number(req.query.page) || 1; const size Number(req.query.size) || 10; const start (page - 1) * size; res.json({ data: ORDERS.slice(start, start size), total: ORDERS.length }); } };这样 Mock 数据更接近真实接口前端开发时就能验证分页、筛选等逻辑。6.2 多环境构建配置ng-alain 默认有environment.ts和environment.prod.ts但实际项目往往需要更多环境比如测试环境、预发环境。改造时在angular.json里加配置configurations: { production: {...}, staging: { fileReplacements: [ { replace: src/environments/environment.ts, with: src/environments/environment.staging.ts } ] } }然后ng build --configurationstaging就能打出测试环境的包。6.3 构建优化的几个关键点构建优化我一般做三件事开启 AOTAngular 默认已开、开启构建缓存、按需加载第三方库。ng-alain 依赖的delon/*包体积不小如果全量引入会拖慢首屏。我的做法是只引入用到的模块比如不用 Chart 就不引入delon/chart。另外angular.json里的budgets配置要调整默认的 bundle 大小限制是 2MB中后台项目很容易超。我一般调到 5MB同时开启sourceMap: false减小产物体积。注意构建优化不要过度。我见过有团队为了减小体积把 NG-ZORRO 的样式按需引入结果某些组件的样式丢失排查了半天。按需引入要确保覆盖所有用到的组件宁可体积大一点也不要样式出问题。7. 改造后的验证与回归改造完成后不能直接提交要做一轮完整的验证。我一般按这个清单过一遍验证项验证方式通过标准路由跳转手动点击所有菜单无 404无白屏懒加载查看 Network 面板各模块 chunk 按需加载权限控制不同角色账号登录菜单和按钮显示正确布局切换访问不同布局页面布局正确切换Mock 接口调用所有 Mock 接口返回数据格式正确构建产物执行生产构建无报错体积在预算内这个清单看着简单但每一项都可能藏问题。比如懒加载如果某个模块被别的模块直接 import 了就不会生成独立 chunkNetwork 面板里看不到。这种问题不验证根本发现不了。8. 我在改造中踩过的几个典型坑最后分享几个我实际踩过的坑都是文档里不会写的。第一个坑是路径别名和 Jest 的冲突。配了core/*别名后ng serve正常但 Jest 测试报找不到模块。原因是 Jest 不读tsconfig.json的paths需要在jest.config.js里单独配moduleNameMapper。这个坑我排查了两个小时。第二个坑是懒加载模块的样式隔离。Angular 的组件样式默认是Emulated模式懒加载模块的样式不会影响全局。但如果某个模块用了ViewEncapsulation.None它的样式会泄漏到其他模块。我在一个项目里因为订单模块用了None导致用户模块的按钮样式被覆盖排查了很久。第三个坑是路由复用的内存泄漏。开启路由复用后组件实例不会销毁如果组件里订阅了Observable但没取消就会内存泄漏。我的做法是在ngOnDestroy里统一取消订阅或者用takeUntil模式。第四个坑是权限缓存的过期问题。用户权限变更后如果前端还读旧缓存会出现权限不一致。我的做法是在 token 刷新时同步刷新权限缓存同时在关键操作前做一次权限校验。这些坑的共同点是它们不会在开发时报错只会在特定场景下暴露。所以改造后的验证一定要覆盖各种边界场景不能只测正常流程。改造 ng-alain 项目这件事说到底是在框架的“通用性”和业务的“特殊性”之间找平衡。框架给的是最大公约数你要做的是把它裁剪成适合自己团队的样子。裁剪的过程中保持渐进、保持可验证、保持对框架核心能力的尊重就不会出大问题。