如何升级ng-jhipster库以兼容Angular 16.2.0？

问题背景 #

当前开发的Angular应用依赖ng-jhipster@0.16.0，该库的package.json配置如下：

{
  "name": "ng-jhipster",
  "description": "A Jhipster util library for Angular",
  "repository": {
    "type": "git",
    "url": "https://github.com/jhipster/ng-jhipster.git"
  },
  "keywords": [
    "jhipster",
    "angular",
    "angular2"
  ],
  "author": "Deepu KS",
  "license": "Apache-2.0",
  "bugs": {
    "url": "https://github.com/jhipster/generator-jhipster/issues"
  },
  "homepage": "https://www.jhipster.tech",
  "peerDependencies": {
    "@angular/core": "^10.0.0",
    "@angular/router": "^10.0.0",
    "@angular/common": "^10.0.0",
    "@angular/forms": "^10.0.0",
    "@ng-bootstrap/ng-bootstrap": "^6.1.0 || ^7.0.0",
    "@ngx-translate/core": "^12.1.2 || ^13.0.0",
    "@ngx-translate/http-loader": "^5.0.0 || ^6.0.0",
    "@fortawesome/angular-fontawesome": "^0.6.1 || ^0.7.0",
    "@fortawesome/fontawesome-svg-core": "^1.2.21",
    "@fortawesome/free-solid-svg-icons": "^5.10.1",
    "rxjs": "^6.5.2"
  },
  "devDependencies": {
    "@angular/animations": "^10.0.0",
    "@angular/common": "^10.0.0",
    "@angular/compiler": "^10.0.0",
    "@angular/compiler-cli": "^10.0.0",
    "@angular/core": "^10.0.0",
    "@angular/forms": "^10.0.0",
    "@angular/platform-browser": "^10.0.0",
    "@angular/platform-browser-dynamic": "^10.0.0",
    "@angular/platform-server": "^10.0.0",
    "@angular/router": "^10.0.0",
    "@fortawesome/angular-fontawesome": "0.6.1",
    "@fortawesome/fontawesome-svg-core": "^1.2.28",
    "@fortawesome/free-solid-svg-icons": "^5.13.0",
    "@ng-bootstrap/ng-bootstrap": "^6.0.0",
    "@ngx-translate/core": "^12.1.1",
    "@ngx-translate/http-loader": "^5.0.0",
    "@types/jest": "26.0.3",
    "@types/node": "13.13.4",
    "@typescript-eslint/eslint-plugin": "^2.30.0",
    "@typescript-eslint/eslint-plugin-tslint": "^2.30.0",
    "@typescript-eslint/parser": "^2.30.0",
    "codelyzer": "^5.2.1",
    "core-js": "^3.6.4",
    "eslint": "^6.8.0",
    "eslint-config-jhipster": "0.0.1",
    "eslint-config-prettier": "^6.10.0",
    "husky": "4.2.5",
    "jest": "26.1.0",
    "jest-preset-angular": "8.2.1",
    "lint-staged": "9.2.3",
    "ng-packagr": "^10.0.0",
    "prettier": "^2.0.5",
    "reflect-metadata": "0.1.13",
    "rimraf": "^3.0.2",
    "rxjs": "^6.5.4",
    "tsickle": "0.36.0",
    "tslint": "^6.0.0",
    "typescript": "3.9.5",
    "zone.js": "0.10.2"
  },
  "version": "0.16.0",
  "lint-staged": {
    "{,src/**/}*.{md,json,ts,html}": [
      "prettier --write",
      "git add"
    ]
  },
  "scripts": {
    "cleanup": "rimraf dist/*",
    "format": "prettier --write \"{,src/**/}*.{md,json,ts,html}\"",
    "lint": "eslint . --ext .ts",
    "lint:fix": "npm run lint -- --fix",
    "test": "npm run lint && jest --config tests/jest.conf.js",
    "test:watch": "npm run test -- --watch",
    "build": "ng-packagr -p ng-package.prod.json",
    "build:dev": "ng-packagr -p ng-package.dev.json --watch",
    "release": "git push && git push --tags && npm publish dist/",
    "clean-release": "npm run cleanup && npm run build && npm run release",
    "release:patch": "npm test && npm version patch -a -m \"Update to %s\" && npm run clean-release",
    "release:minor": "npm test && npm version minor -a -m \"Update to %s\" && npm run clean-release",
    "release:major": "npm test && npm version major -a -m \"Update to %s\" && npm run clean-release"
  }
}

需要将应用升级到Angular 16.2.0，但该库仅支持最高Angular 10.0.0，以下是升级ng-jhipster以兼容Angular 16的步骤与最佳实践：

推荐升级步骤与最佳实践 #

1. 先评估依赖范围，优先考虑替代方案 #

• 梳理项目中实际用到的ng-jhipster功能模块，比如翻译工具、表单组件、路由守卫、通用服务等，判断是否可以用Angular原生API或活跃的第三方库替代，比如用Angular原生国际化API替代ng-jhipster的翻译逻辑，减少后续改造工作量
• 检查该库的源码仓库，确认是否有社区维护的fork或分支已经完成高版本Angular适配，直接基于这些分支改造能节省大量时间

2. 同步环境与依赖版本 #

• 克隆ng-jhipster仓库到本地，更新package.json中的依赖版本：
  • 将peerDependencies和devDependencies中的所有Angular相关包（@angular/core、@angular/router等）版本统一改为^16.2.0
  • 更新关联依赖：@ng-bootstrap/ng-bootstrap替换为兼容Angular 16的版本（如^15.1.0）、@ngx-translate/core升级到^15.0.0以上、rxjs改为^7.8.0（Angular 16要求RxJS 7.x）、typescript升级到^5.1.3（Angular 16的TypeScript版本要求）
  • 移除过时工具：删除tslint、codelyzer，替换为@angular-eslint相关配置；更新ng-packagr到^16.0.0，适配Angular 16的构建要求
  • 更新测试工具：jest升级到^29.5.0，jest-preset-angular改为^13.1.1（兼容Angular 16）

3. 代码适配Angular 16的API变更 #

• 处理Angular版本迭代带来的破坏性变更：
  • 替换ViewEngine相关代码为Ivy兼容写法（Angular 12+已默认启用Ivy）
  • 调整生命周期钩子、表单API、路由API的使用方式，比如Angular 14+中FormBuilder的类型推导变化，Router的导航方法参数调整
• 修复TypeScript类型错误：由于TS版本升级，部分类型注解、泛型使用会出现不兼容，需要逐一调整
• 适配RxJS 7的变化：替换RxJS 6中已废弃的操作符（如forkJoin的用法），调整Observable的创建与订阅逻辑

4. 构建与测试验证 #

• 更新ng-package.prod.json和ng-package.dev.json配置，确保符合ng-packagr 16的构建规范
• 调整scripts中的命令：比如更新测试命令的配置路径，适配新版jest的要求
• 执行npm install安装新依赖，解决依赖冲突（可使用npm install --force临时跳过部分冲突，后续再逐一修复）
• 运行npm run build构建库，修复构建过程中的编译错误、打包配置问题
• 执行npm run test运行测试用例，修复测试失败的问题，确保核心功能逻辑正常

5. 集成到Angular 16项目中验证 #

• 将本地构建好的ng-jhipster包（dist目录下）通过npm install ../path/to/ng-jhipster/dist安装到目标Angular 16项目中
• 启动项目，检查控制台的运行时错误，重点验证之前用到的ng-jhipster功能是否正常工作
• 逐步迁移项目中依赖ng-jhipster的代码，优先替换为Angular原生实现，降低对改造后库的依赖

6. 长期维护策略 #

• 如果官方无更新计划，将改造后的ng-jhipster作为私有npm库维护，定期同步Angular新版本的变化
• 制定长期迁移计划，逐步移除对ng-jhipster的依赖，改用Angular原生功能或更活跃的第三方库，避免未来再次遇到版本兼容瓶颈

内容的提问来源于stack exchange，提问作者Sumit Arora