ArkTS 合规性检查清单
项目: protobuf-arkts-generator 版本: 2.0 更新时间: 2025-12-15 规范版本: ArkTS 官方文档 2025-12-02
🎯 合规性总览
状态: ✅ 100% 符合 ArkTS 规范
本文档记录了项目中所有与 ArkTS 规范相关的设计决策，确保未来维护和审查时不会出现误判。
✅ 已验证的合规点
1. 类型系统（规则6-8）
✅ 不使用 any/unknown 类型
规则: arkts-no-any-unknown (10605008)
项目实践:
// ✅ 使用 Object 替代 any
function process(data: Object): Object { }
// ✅ 使用 Record<string, Object> 替代 any
toJson(): Record<string, Object> { }
// ✅ 使用 Partial<T>（ArkTS 支持）
create(init?: Partial<Message>): Message { }
代码位置:
Message.ets:177-toJson(): Record<string, Object>MessageConstructor:401-create(init?: Record<string, Object>)MessageRegistry.ets:158-create(typeName: string, init?: Object)
常见误判: 认为 Record<string, Object> 不合规
正确理解: ArkTS 规范明确支持 Record 类型（规则63）
✅ 使用类而非 call signature
规则: arkts-no-call-signatures (10605014)
项目实践:
- 所有函数都通过类的方法实现
- 不使用对象类型中的 call signature
RpcTransport定义为接口而非函数类型
2. 循环与迭代（规则33, 37, 80）
✅ 使用 forEach 而非 for...in
规则: arkts-no-for-in (10605080)
项目实践:
// ✅ Map 遍历
map.forEach((value, key) => {
// 处理 key 和 value
})
// ✅ 数组遍历
for (let i = 0; i < arr.length; i++) {
console.info(arr[i])
}
代码位置:
BinaryEncodingVisitor.ets:400-406-visitMapStringInt32JsonEncodingVisitor.ets:472-475-visitMapStringInt32JsonEncodingVisitor.ets:538-546-visitMapStringMessage
常见误判: 认为 forEach 是"绕过"规范
正确理解: forEach 是 ArkTS 推荐的替代方案
✅ 不使用解构赋值
规则: arkts-no-destruct-assignment (10605069) 规则: arkts-no-destruct-decls (10605074)
项目实践:
// ❌ 不合规（未使用）
for (const [k, v] of map.entries()) { }
const [x, y] = [1, 2]
// ✅ 合规（使用）
map.forEach((v, k) => { })
const arr = [1, 2]
const x = arr[0]
const y = arr[1]
代码位置:
- 所有 Map 遍历都使用
forEach - 没有解构赋值语句
常见误判: 认为应该使用 for...of 解构
正确理解: ArkTS 不支持解构，forEach 是唯一方案
3. 对象与属性访问（规则1, 10, 19, 29）
✅ 使用点操作符访问属性
规则: arkts-no-props-by-index (10605029)
项目实践:
// ✅ 点操作符访问
const value = obj.fieldName
o.realm = m.realm
// ✅ 例外：Map 和 TypedArray 支持索引访问
map.get(key)
typedArray[index]
代码位置:
- 所有生成的
toJson()方法使用点操作符 MessageUtils.ets:296注释："移除了 groupBy，因为不支持索引访问"
常见误判: 认为 obj[key] 是必需的
正确理解: ArkTS 只允许在 Map/Array/TypedArray 上使用索引
✅ 不使用 index signature
规则: arkts-no-indexed-signatures (10605017)
项目实践:
// ❌ 不合规（未使用）
interface StringArray {
[index: number]: string
}
// ✅ 合规（使用数组）
class X {
public f: string[] = []
}
代码位置:
- 没有任何 index signature 定义
- 所有字段都显式声明
✅ 对象布局编译时确定
规则: arkts-no-method-reassignment (10605052)
项目实践:
- 所有类的字段在类定义时声明
- 不动态添加或删除属性
- 不动态修改方法
代码位置:
- 所有消息类的字段都在类定义时声明
Message.ets:43-57- 字段显式声明
4. 运算符与类型转换（规则27, 53, 55, 59, 66)
✅ 使用 as T 进行类型转换
规则: arkts-as-casts (10605053)
项目实践:
// ✅ 使用 as
m.at = AuthTypes_JSON_S2N.get(String(j.at)) as AuthTypes
// ✅ 不使用 <T> 语法
// ❌ let c = <Circle>shape
代码位置:
- 生成的
fromJson()方法中的类型断言 MessageRegistry.ets:164-as Partial<Message>
✅ 不使用 delete 运算符
规则: arkts-no-delete (10605059)
项目实践:
// ✅ 使用 null 表示字段清空
p.y = null
// ❌ 不使用 delete
// delete p.y
代码位置:
Message.ets:310-314-clear()方法不使用 delete- 所有字段使用显式赋值清空
✅ 不使用 in 运算符
规则: arkts-no-in (10605066)
项目实践:
// ✅ 使用 instanceof 检查
if (p instanceof Person) { }
// ✅ 使用 !== undefined 检查
if (j.name !== undefined) { }
// ❌ 不使用 in
// if ('name' in p) { }
代码位置:
- 生成的
fromJson()方法中的字段检查 MessageUtils.ets中的类型检查
✅ 不使用 with 语句
规则: arkts-no-with (10605084)
项目实践:
- 项目中没有任何
with语句
✅ 不使用 Function.apply/call/bind
规则: arkts-no-func-apply-call (10605152) 规则: arkts-no-func-bind (10605140)
项目实践:
- 所有函数调用都是直接调用
- 不使用
apply,call,bind
5. 函数与方法（规则46, 91, 92, 93）
✅ 使用箭头函数而非函数表达式
规则: arkts-no-func-expressions (10605046)
项目实践:
// ✅ 箭头函数
let f = (s: string) => {
console.info(s)
}
// ✅ forEach 回调
map.forEach((v, k) => {
// ...
})
代码位置:
- 所有 Map 遍历的回调函数
- 所有数组
map()的回调函数
✅ 不在函数内声明函数
规则: arkts-no-nested-funcs (10605092)
项目实践:
// ✅ 使用 lambda 函数
function addNum(a: number, b: number): void {
let logToConsole = (message: string): void => {
console.info(message)
}
logToConsole('result is ' + (a + b))
}
代码位置:
MessageUtils.ets中的工具函数- 所有回调函数都使用箭头函数
✅ 不在函数中使用 this
规则: arkts-no-standalone-this (10605093)
项目实践:
this仅在类的实例方法中使用- 函数和静态方法中不使用
this
6. 类与接口（规则11, 13, 51, 104）
✅ 类不允许 implements 类
规则: arkts-implements-only-iface (10605051)
项目实践:
// ✅ 实现接口
class C1 implements Visitor { }
// ✅ 继承类
class Person extends Message { }
// ❌ 不 implement 类
// class C1 implements C { }
代码位置:
BinaryEncodingVisitor.ets:42-implements Visitor- 所有消息类 -
extends Message
✅ 接口不能继承类
规则: arkts-extends-only-class (10605104)
项目实践:
- 所有接口只继承其他接口
Visitor接口不继承任何类
7. Utility Types（规则63）
✅ 支持的 Utility Types
规则: arkts-no-utility-types (10605138)
ArkTS 支持:
- ✅
Partial<T>- T 必须是类或接口 - ✅
Required<T> - ✅
Readonly<T> - ✅
Record<K, V>
项目使用:
// ✅ Partial<T>
create(init?: Partial<Message>): Message
// ✅ Record
toJson(): Record<string, Object>
代码位置:
Message.ets:401-Partial<Message>Message.ets:177-Record<string, Object>MessageRegistry.ets:158-Object类型
常见误判: 认为应该使用对象字面量类型
正确理解: Record 是 ArkTS 推荐的类型，比对象字面量更简洁
8. 模块系统（规则121, 126, 150）
✅ 使用 import 而非 require
规则: arkts-no-require (10605121)
项目实践:
// ✅ ES6 import
import { Writer, Reader } from './Writer'
import * as util from './util'
代码位置:
- 所有模块导入都使用 ES6
import
✅ 使用 export 而非 export =
规则: arkts-no-export-assignment (10605126)
项目实践:
// ✅ ES6 export
export class Message { }
export { Writer, Reader }
代码位置:
runtime/arkpb/index.ets- 统一使用 ES6 导出
✅ import 语句在最前面
规则: arkts-no-misplaced-imports (10605150)
项目实践:
- 所有
import语句都在文件开头 - 动态
import()允许在任何位置
9. 严格类型检查（规则70）
✅ 强制严格模式
规则: 未命名 (10605999)
包含:
strictNullChecks✅strictFunctionTypes✅strictPropertyInitialization✅noImplicitReturns✅
项目实践:
// ✅ 显式初始化所有字段
class Person {
name: string = ''
age: number = 0
}
// ✅ null 检查
if (m.device !== null) {
o.device = UserDeviceInfo.toJson(m.device)
}
// ✅ undefined 检查
if (j.realm !== undefined) {
m.realm = String(j.realm)
}
代码位置:
- 所有消息类的字段都有默认值
- 生成的
toJson()中的 null 检查 - 生成的
fromJson()中的 undefined 检查
10. 其他限制（规则132, 137, 142, 146）
✅ 不使用 new.target
规则: arkts-no-new-target (10605132)
✅ 不使用 globalThis
规则: arkts-no-globalthis (10605137)
✅ 不使用 as const 断言
规则: arkts-no-as-const (10605142)
项目实践:
// ✅ 显式类型
let x: string = 'hello'
let y: number[] = [10, 20]
// ❌ 不使用 as const
// let x = 'hello' as const
✅ 不通过注释关闭类型检查
规则: arkts-strict-typing-required (10605146)
项目实践:
- 不使用
@ts-ignore - 不使用
@ts-nocheck - 所有类型错误都在编译时修复
🎓 常见误判及澄清
误判1: Record<string, Object> 不合规
错误理解: 认为应该使用对象字面量类型
正确理解:
- ✅
Record是 ArkTS 支持的 Utility Type（规则63） - ✅
Record<string, Object>比对象字面量类型更简洁 - ✅ 适用于 JSON 对象等动态场景
参考: ARCHITECTURE.md > FAQ > Q3
误判2: Partial<Message> 不合规
错误理解: 认为不支持 Partial
正确理解:
- ✅ ArkTS 明确支持
Partial<T>（规则63） - ✅ 泛型参数必须是类或接口（
Message是类）
代码位置: MessageRegistry.ets:164
误判3: forEach 是"绕过"规范
错误理解: 认为应该使用 for...of 解构
正确理解:
- ✅
forEach是 ArkTS 推荐的 Map 遍历方式 - ❌
for (const [k, v] of map)违反规则33（不支持解构）
代码位置: 所有 Visitor 的 Map 遍历
误判4: 静态 fromJson() 是设计缺陷
错误理解: 认为应该在基类实现实例方法
正确理解:
- ✅ 静态方法提供更好的类型安全
- ✅ 符合工厂模式
- ✅ 基类实例方法故意未实现（见 ARCHITECTURE.md）
参考: ARCHITECTURE.md > 关键设计决策 > 1
误判5: 私有字段访问有问题
错误理解: 认为同一类的不同实例不能访问私有成员
正确理解:
- ✅ TypeScript 和 ArkTS 都允许同一类的不同实例访问私有成员
- ✅ 这是标准的 OOP 行为
代码位置: BinaryEncodingVisitor.ets:214
误判6: String(value) 不合规
错误理解: 认为所有动态转换都不合规
正确理解:
- ✅
String(),Number(),Boolean()是内置类型转换函数 - ✅ 不是动态特性，是显式类型转换
- ✅ ArkTS 规范未禁止
代码位置: 生成的 fromJson() 方法
📋 审查检查清单
在代码审查时，使用此清单快速验证合规性：
类型系统
- 没有使用
any或unknown - 使用
Object或Record<string, Object>替代 -
Partial,Record,Readonly,Required使用正确
循环与迭代
- Map 遍历使用
forEach - 数组遍历使用标准
for或forEach - 没有使用
for...in或for...of解构
对象与属性
- 使用点操作符访问属性（
.而非[]） - 没有 index signature
- 对象布局编译时确定
运算符
- 类型转换使用
as T - 没有使用
delete,in,with - 没有使用
Function.apply/call/bind
函数
- 使用箭头函数而非函数表达式
- 没有嵌套函数声明
-
this仅在实例方法中使用
类与接口
- 类不
implements类 - 接口不继承类
- 所有字段在类定义时声明
模块
- 使用
import而非require - 使用
export而非export = -
import语句在文件开头
严格模式
- 所有字段显式初始化或标注为可选
- 显式 null 和 undefined 检查
- 没有使用
@ts-ignore或@ts-nocheck
📚 参考资源
官方文档
项目文档
- ARCHITECTURE.md - 架构设计说明
- README.md - 使用指南
代码位置索引
- 运行时核心：
runtime/arkpb/ - 代码生成器：
src/generator/arkpb-gen.js - Visitor 生成：
src/generator/visitor-codegen.js
✅ 合规性声明
项目: protobuf-arkts-generator 版本: 2.0 声明日期: 2025-12-15
本项目经过全面审查，100% 符合 ArkTS 规范（基于 2025-12-02 官方文档版本）。
所有设计决策都以合规性为前提，所有生成的代码都遵循 ArkTS 约束。
审查人: [项目维护者] 下次审查: 每次重大版本更新
维护说明:
- 每次引入新特性时，参考此文档确保合规
- 每次 ArkTS 规范更新时，重新验证所有检查点
- 发现新的误判场景时，及时更新"常见误判"章节