快速上手

环境要求

依赖 版本 说明
JDK 21+ 使用 Java 21 语法（record / sealed / pattern matching）
Maven 3.9+ 构建
操作系统 Linux / macOS / Windows 三个平台各有对应的启停脚本

不需要数据库服务：元数据存本地 SQLite（首次启动自动创建）。

三种启动方式

1. 下载发布包（推荐）

Linux / macOS

curl -LO https://github.com/geek-xin/code-association/releases/latest/download/code-association-0.3.0.tar.gz
tar -xzf code-association-0.3.0.tar.gz
cd code-association-0.3.0

./start.sh          # 默认 9996 端口
./start.sh 8080     # 指定端口
./stop.sh           # 停止

Windows：下载 code-association-0.3.0.zip 解压（用 Windows 自带解压，保留 CRLF），然后：

start.bat           :: 默认 9996 端口
start.bat 8080      :: 指定端口
stop.bat            :: 停止

start.bat 内部带 -ExecutionPolicy Bypass 调用 start.ps1，不需要改系统执行策略。

start.sh 会把进程从当前 shell 完全脱离（PPID=1、独立进程组），关掉终端不会带走服务； Windows 上 start.ps1 以隐藏窗口后台启动。两者的应用日志都写在 logs/code-association.log（按天滚动、保留 7 天，ERROR 另见 logs/code-association-error.log）， 进程原始输出写在 logs/console.log（Windows 另有 logs/console.err.log 收 stderr）， PID 写到 .code-association.pid。目录、事件名与排查命令见 日志规范。

start.sh 不硬依赖 python3 / lsof / curl：Linux 优先 setsid 脱离终端， macOS 用 python3 双 fork，两者都没有时退化为 nohup 并提示；健康检查优先 curl， 否则用 bash /dev/tcp。详见 INSTALL.md。

2. 从源码构建

git clone git@github.com:geek-xin/code-association.git
cd code-association
mvn -q -DskipTests package
./start.sh          # Windows: start.bat

3. 前台运行（调试用，三平台通用）

java -jar target/code-association.jar --server.port=9996

跑通第一次分析

  1. 打开 http://127.0.0.1:9996
  2. 左侧「代码源」→ 添加两个程序：
    • 一个是被改动的程序（例如 order-service）
    • 一个是可能被波及的程序（例如 user-service）
  3. 右上角「新建分析」→ 选择被改动的程序
  4. 在弹窗底部勾选「同时比较其他程序」→ 选中另一个程序
  5. 「开始分析」

为什么必须选两个？ 扫描范围只有其他程序。只选一个时没有对比对象， 报告里不会有任何影响条目——这是设计如此，不是 bug。

使用私有 GitLab 仓库

公开仓库填地址即可；私有仓库要先让服务拿到 GitLab 个人访问令牌（PAT）。推荐在设置页配置： 保存即生效，不用重启，也不用先导出环境变量。

  1. 创建令牌。 GitLab →「Preferences → Access Tokens」，勾选 read_repository（至少），复制令牌。
  2. 保存到设置页。 左侧「设置」→「GitLab 私有仓库」卡片 → 粘贴令牌 →「保存」。 已保存时输入框是空的，占位符里的「已保存 glpa…cdef」是掩码，留空保存表示不修改； 只有「清除」才真正删掉令牌。
  3. 添加代码源。 「代码源」→ 添加，来源类型选 GITLAB，位置填 HTTPS 克隆地址 （https://gitlab.com/group/repo.git，自建实例如 https://gitlab.example.com/group/repo.git）。
  4. 验证。 填完地址后分支下拉能自动列出远端分支，说明令牌被接受；下拉为空并提示认证失败时 见 故障排查。

另有一条不落库的路径：在代码源的「凭据环境变量」里填变量名（如 GITLAB_TOKEN）， 服务从环境变量读取令牌。同名变量有值时优先于设置页令牌；命令行与 CI 通常用这条 （见 命令行与 CI）。

来源类型必须是 GITLAB：GITHUB / GIT 类型不会附加这个令牌。 GitLab 的部署令牌（deploy token）需要用户名配对，也不适用。

第一次该看什么

分析完成后，总览页只有一张「对其他程序的影响」卡片：顶部是对比程序汇总， 下面按风险列出前 6 条影响，点击任意一条进入审核与证据。

[peer-b · 1 契约 · 2 处]  [peer-c · 未比较]
UserClient#fetchUser      [高]
调用方按 int 接收返回值    peer-b · API_CONTRACT · 置信度 HIGH · [待复核]
OrderService#canOrder     [高]
...（还有 3 条影响，点「查看全部」进入审核）

影响审核页把对比程序汇总收进发现列表标题下（每个程序一枚 pill：契约数 / 影响处数）， 逐条影响只在列表里出现一次；右侧面板在未选中发现时展示完整的契约命中与对方使用点，选中后切换成逐跳传播路径； 每条证据还会把引用行所在的整个方法或代码块内联出来——片段上方一行小字写明「方法 · 第 12–48 行」这样的范围， 超过 160 行的块只展示引用行附近——不必再打开仓库核对。总览只保留”会影响谁、先看哪几条”这一层，避免同一个影响 在两个页面里重复出现。

验证安装是否正常

curl http://127.0.0.1:9996/api/health
# {"status":"ok","dataDir":".../.code-association","maxDepth":8,"maxFiles":20000,"aiEnabled":false}

curl http://127.0.0.1:9996/api/schedule
# {"enabled":true,"cron":"0 30 2 * * *",...}

下一步