SuperAPI AI 工具集

ts-principles

通用与其它

查看项目

更新于 10-16 06:16

技能介绍

用途:ts-principles 是一份核心工程原则参考,供设计、规划与代码评审时作为指导。资料说明使用时应先阅读该文件,把其中的要点视为规范简写,并默认继续阅读更深入的原则文档,除非提示另有说明。

主要能力(按主题):

  • 按领域塑造代码:精确命名名词与动词,同一领域概念使用同一内部术语,优先领域语言而非技术机制,按 users、machines、orders 而非 components、controllers、repositories、routes 组织;避免 data、entity、item、manager、helper 等宽泛名称;在边界处翻译外部、遗留、UI 标签与同义词;避免大杂烩式 utils,可抽取的库式代码放入 lib,其余与领域就近放置。
  • 保持边界清晰:跨模块消歧关注点,避免实现细节泄漏,在边缘把外部概念映射为内部概念,优先显式依赖,跨数据与协议边界传数据而非行为。
  • 解析而非校验:在每个边界(IO、HTTP、DB、配置、队列、环境变量)解析未知值,优先类型安全而非强制转换与防御式编程,统一使用一个 schema 库,把强制转换、提取、规范化与领域变换放入边界 schema;可信代码中的 parse*/validate* 调用视为坏味道;解析应产出更小、可信的类型;优先可辨识联合而非可选属性变体。
  • 权限需被授予:把调用方控制的输入、身份、来源与外部系统视为不可信,先认证身份再使用,对目标资源逐操作授权,默认拒绝模糊访问,授予最小权限,密钥不得进入源码、日志、错误、遥测、URL 与客户端,只返回调用方有权知道的数据,约束文件系统、网络、浏览器与第三方能力,把攻击者触发的资源耗尽视为安全缺陷。
  • 处理或崩溃:预期失败是具名领域错误,经 Effect 错误通道、Result 等承载;意外缺陷是 bug,任其爆炸;内部把库错误映射为领域错误,边界把领域错误映射为协议错误;避免 catch-log-rethrow;未处理错误只在边界记录一次;不变量损坏后不要继续;不要把程序员 bug 编码为可恢复业务错误。
  • 避免草率抽象:为当下而写,重复到清晰模式出现再抽象,只抽象已被证实的重复;配置也是抽象,只提升真正变化的部分;不共享且不太可能变化的值内联;一次性代码保持内联,除非抽取同时改善调用方与函数体;不要仅为命名而抽取微小对象构造器或透传包装。
  • 性能不可选:把延迟与资源使用视为行为,提交形态前先建模请求成本,为条目数、扇出、字节、行数、内存、重试与并发命名边界,测量尾延迟、饱和度与错误而非只看均值,检查 CPU、内存、磁盘、网络、连接池、锁、队列与依赖等阻塞资源,把并发视为预算,过载填满队列前拒绝、卸载、延迟或降级,优先避免工作而非加速工作,明确缓存大小、新鲜度、失效与失败模式,避免意外二次方工作、话痨 IO、无界内存、队列增长与分配抖动。
  • 测试即代码:像生产代码一样对待测试,只为行为、契约、边界、回归或失败重要的稳定不变量添加测试;不测常量、纯类型接线、仅渲染组件、透传包装或框架管道;优先公共行为、边界与接口而非内部;优先普通代码与数据相等而非重框架测试机制;重复数据用例优先 .test.each / .it.each;把复述实现、重复检查或在无害重构中失败的测试视为缺陷;避免复杂冗长断言块;优先用 schema 解析测试输出或简单单次相等检查;优先错误类型或标签检查而非错误消息检查;优先真实代码,只 mock 外部;用集成/E2E 测试真实边界行为;测试反事实;属性测试只用于持久不变量。
  • 集成式文档:记录为什么、上下文、决策、约束与契约;把文档放在读者会看的地方;按读者任务匹配文档形态:教程、操作指南、参考或解释;把公开文档、命令、配置片段与示例视为契约;优先用 /** ... */ 记录接口;避免名称、类型、schema 或测试已覆盖的冗余文档;优先单一事实来源与链接而非重复叙述;行为变更同一 diff 更新文档;删除过时文档。
  • 对抗熵:假设善意而非良好上下文;不延续坏代码模式;让代码比你发现时更干净,但保持改动范围;触及区域中坏或过时的测试可清除;改动已触及代码时机会性重构。
  • 状态即值:把不可能状态建模为不可能;命名进行中状态(Pending、Settling、Retrying),不只终态;不存储可廉价派生的状态。
  • 按适配选择范式:控制或性能重要、更清晰时用命令式;多数领域/应用逻辑用 FP 风格:纯函数、不可变值、组合与显式效果;身份、生命周期、资源所有权或封装可变状态为核心时用 OO;抽取被证实时,纯无状态逻辑用顶层函数,依赖实例状态、构造注入依赖、生命周期或封装的行为用方法;不要把方法改成函数却传入半个对象作参数;边界避免 OO,交换普通数据;避免继承,优先组合与小型显式接口;不要为所有问题标准化单一范式。
  • 有意演进契约:把持久数据、外部模型、公开 API、事件与队列视为长期契约;改契约前先了解有哪些消费者;不要假设总是需要向后兼容;需要兼容时优先增量变更;风险高时把 schema 变更与行为变更分开;滚动部署时考虑旧读写方;不再需要时删除兼容代码。
  • 为运维而设计:尽可能让长任务可取消;有意使用超时、重试与背压;发出足够可观测性以便无需复现即可调试失败;优先可操作日志而非嘈杂日志。

使用方式:资料要求先读该文件,把要点作为规范简写,并默认继续阅读更深入的原则文档,除非提示另有说明。

适用场景:TypeScript 项目的设计、规划与代码评审,作为工程决策的指导参考。

限制:资料未提供安装命令、代码示例、收费或平台信息,暂未提供。