如何将项目中公共模块封装为可复用Skill：从设计模式到工程实践

2次阅读

没有评论

共计 2455 个字符，预计需要花费 7 分钟才能阅读完成。

去年参与一个微服务改造项目时，发现六个子系统各自实现了权限校验模块。虽然业务规则相同，但由于实现差异导致：

新员工需要阅读 5 种不同风格的鉴权代码
修复越权漏洞时需同步修改 6 个代码库
性能优化方案无法统一实施

这让我意识到： 公共模块的碎片化实现是研发效能的第一杀手 。

传统 Utils 类通常存在两大缺陷：

强耦合 ：静态方法直接依赖具体实现

// 反例：硬编码的加密工具类
public class CryptoUtils {public static String encrypt(String input) {return AES.encrypt(input); // 无法替换算法
    }
}

无契约 ：方法签名即全部约定

Skill 化方案通过接口隔离原则改进：

// Skill 标准接口
interface LoggingSkill {
  /**
   * @param level 日志级别
   * @param message 支持结构化数据
   */
  log(level: LogLevel, message: LogEntry): Promise<void>;
}

// 实现端遵守接口契约
class ELKLogger implements LoggingSkill {async log(level: LogLevel, entry: LogEntry) {
    await elkClient.index({index: `logs-${new Date().toISOString().slice(0,10)}`,
      body: {...entry, severity: level}
    });
  }
}

遵循三个关键原则：

单一职责 ：每个 Skill 只解决一个问题域
显式依赖 ：所需资源通过构造函数注入
异常契约 ：明确声明可能抛出的错误类型

/**
 * 权限校验 Skill
 * @throws AccessDeniedException 当校验失败时抛出
 */
public interface AuthSkill {void checkPermission(User user, Resource resource) 
        throws AccessDeniedException;
}

Spring 集成示例：

@SkillComponent // 自定义注解标识 Skill
public class DatabaseAuthSkill implements AuthSkill {
    private final UserRepository repo;

    @Autowired
    public DatabaseAuthSkill(UserRepository repo) {this.repo = repo;}

    @Override
    public void checkPermission(User user, Resource res) {// 实现细节...}
}

TypeScript 推荐使用 InversifyJS：

const SKILL_TYPES = {Logging: Symbol.for('LoggingSkill')
};

@injectable()
class WinstonLogger implements LoggingSkill {// 实现代码...}

// 容器配置
const container = new Container();
container.bind<LoggingSkill>(SKILL_TYPES.Logging).to(WinstonLogger);

采用双保险策略：

契约测试 ：验证实现是否符合接口规范

public class AuthSkillContractTest {
    @Test
    public void shouldThrowWhenResourceNotOwned() {AuthSkill skill = createSkillInstance();
        assertThrows(AccessDeniedException.class, 
            () -> skill.checkPermission(guestUser, premiumResource));
    }
}

模拟测试 ：验证 Skill 与上下游交互

describe('ELKLogger', () => {it('should send log to daily index', async () => {const mockClient = { index: jest.fn() };
        const logger = new ELKLogger(mockClient);

        await logger.log('INFO', { event: 'test'});

        expect(mockClient.index).toHaveBeenCalledWith(
            expect.objectContaining({index: expect.stringMatching(/^logs-\\d{4}-\\d{2}-\\d{2}$/)
            })
        );
    });
});

遵循语义化版本控制 (SemVer)
提供迁移指南（Migration Guide）
维护变更日志（CHANGELOG.md）

@startuml
skinparam monochrome true

component "AuthSkill" as auth {[checkPermission]
}

[checkPermission] -> [Prometheus]: duration histogram
[checkPermission] -> [Sentry]: capture exception
@enduml