🚀 代码规范配置与依赖管理方案

📋 方案概述

本方案为 OpenClaw + Claude Code 端到端研发自动化系统 提供完整的代码规范配置与依赖管理解决方案，覆盖 Java、TypeScript/JavaScript、Python 三种主流技术栈。

🔍 ESLint 配置方案

ESLint 是 JavaScript/TypeScript 的代码检查工具，用于发现和修复代码中的问题。

核心规则配置

{
  "env": {
    "browser": true,
    "es2021": true,
    "node": true,
    "jest": true
  },
  "extends": [
    "eslint:recommended",
    "plugin:react/recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:prettier/recommended"
  ],
  "parser": "@typescript-eslint/parser",
  "plugins": [
    "react",
    "react-hooks",
    "@typescript-eslint",
    "prettier",
    "import"
  ]
}

关键规则说明

使用命令

# 运行代码检查
npm run lint

# 自动修复问题
npm run lint:fix

# 检查并生成报告
npx eslint . --ext ts,tsx --format html -o eslint-report.html

✨ Prettier 配置方案

Prettier 是代码格式化工具，确保代码风格一致性。

核心配置

{
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": true,
  "quoteProps": "as-needed",
  "jsxSingleQuote": false,
  "trailingComma": "all",
  "bracketSpacing": true,
  "arrowParens": "always",
  "endOfLine": "lf"
}

配置说明表

文件覆盖配置

"overrides": [
  {
    "files": "*.json",
    "options": { "printWidth": 120 }
  },
  {
    "files": "*.md",
    "options": { "printWidth": 120, "proseWrap": "always" }
  }
]

☕ CheckStyle 配置方案

CheckStyle 是 Java 代码质量检查工具，基于阿里巴巴 Java 开发手册和 Google Java Style Guide。

核心模块配置

<module name="Checker">
    <property name="charset" value="UTF-8"/>
    <property name="severity" value="warning"/>
    
    <!-- 文件长度检查 -->
    <module name="FileLength">
        <property name="max" value="2000"/>
    </module>
    
    <!-- 行长度检查 -->
    <module name="LineLength">
        <property name="max" value="120"/>
    </module>
    
    <module name="TreeWalker">
        <!-- 命名规范 -->
        <module name="MemberName"/>
        <module name="MethodName"/>
        <module name="ConstantName"/>
        
        <!-- 代码设计 -->
        <module name="FinalClass"/>
        <module name="HideUtilityClassConstructor"/>
        
        <!-- 复杂度指标 -->
        <module name="CyclomaticComplexity">
            <property name="max" value="15"/>
        </module>
    </module>
</module>

命名规范检查

Maven 集成

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-checkstyle-plugin</artifactId>
    <version>3.3.1</version>
    <configuration>
        <configLocation>checkstyle.xml</configLocation>
        <failsOnError>true</failsOnError>
        <consoleOutput>true</consoleOutput>
    </configuration>
    <executions>
        <execution>
            <id>validate</id>
            <phase>validate</phase>
            <goals><goal>check</goal></goals>
        </execution>
    </executions>
</plugin>

📦 Maven 依赖管理

采用多模块架构，统一版本管理，确保依赖一致性。

项目模块结构

核心依赖版本

依赖管理最佳实践

• 统一版本管理：在父 POM 的 <dependencyManagement> 中统一定义版本
• 子模块声明：子模块只声明依赖，不指定版本号
• 排除传递依赖：使用 <exclusions> 排除不需要的传递依赖
• 可选依赖：使用 <optional>true</optional> 标记可选依赖
• Profile 区分环境：使用 Profile 管理 dev/test/prod 不同环境配置

📦 npm 依赖管理

前端项目依赖管理，支持 TypeScript、React、Vite 等现代技术栈。

依赖分类

核心依赖清单

{
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "axios": "^1.6.5",
    "antd": "^5.13.1",
    "zustand": "^4.4.7"
  },
  "devDependencies": {
    "typescript": "^5.3.3",
    "vite": "^5.0.11",
    "eslint": "^8.56.0",
    "prettier": "^3.2.4"
  }
}

版本控制策略

🐍 Python 依赖管理

使用 modern Python 工具链（uv/pip/poetry）进行依赖管理。

推荐使用 uv

uv 是由 Astral 团队用 Rust 编写的超快 Python 包管理器，比 pip 快 10-100 倍。

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建虚拟环境
uv venv

# 安装依赖
uv pip install -r requirements.txt

# 从 pyproject.toml 编译依赖
uv pip compile pyproject.toml -o requirements.txt

核心依赖清单

pyproject.toml 配置

[tool.black]
line-length = 100
target-version = ['py311', 'py312']

[tool.mypy]
python_version = "3.11"
warn_return_any = true
disallow_untyped_defs = true

[tool.pytest.ini_options]
minversion = "7.4"
addopts = "-ra -q --cov=openclaw"
testpaths = ["tests"]

✅ 最佳实践

避免的反模式

🔄 CI/CD 集成

在 Jenkins Pipeline 中集成代码质量检查和依赖管理。

Jenkins Pipeline 示例

pipeline {
    agent any
    
    stages {
        stage('Code Quality') {
            parallel {
                stage('CheckStyle') {
                    steps {
                        sh 'mvn checkstyle:check'
                    }
                }
                stage('ESLint') {
                    steps {
                        sh 'npm run lint'
                    }
                }
                stage('Black') {
                    steps {
                        sh 'black --check src/'
                    }
                }
            }
        }
        
        stage('Build') {
            parallel {
                stage('Build Java') {
                    steps {
                        sh 'mvn clean package -DskipTests'
                    }
                }
                stage('Build Frontend') {
                    steps {
                        sh 'npm run build'
                    }
                }
            }
        }
        
        stage('Test') {
            steps {
                sh 'mvn test'
                sh 'npm run test'
                sh 'pytest'
            }
        }
        
        stage('Deploy') {
            when {
                branch 'main'
            }
            steps {
                sh 'kubectl apply -f k8s/deployment.yaml'
            }
        }
    }
}

GitHub Actions 工作流

name: Code Quality Check

on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Java
        uses: actions/setup-java@v4
        with:
          java-version: '17'
      
      - name: CheckStyle
        run: mvn checkstyle:check
      
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '18'
      
      - name: ESLint
        run: |
          npm install
          npm run lint
      
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      
      - name: Black Format Check
        run: |
          pip install black
          black --check src/

📊 方案总结

本方案提供了完整的代码规范配置与依赖管理解决方案，涵盖以下核心内容：