利用【通义灵码】代码补全增强使用实践

通义灵码提供了企业代码补全增强的能力，在开发者使用通义灵码 IDE 插件的行间代码生成时，可以结合企业上传的代码库作为上下文进行行间代码补全，使代码补全更加贴合企业代码规范、业务特点。本文将分享如何构建高质量的企业代码库，以及开发者在前端和后端开发场景的使用实践。

适用版本与支持语言

适用版本	支持后端	支持前端
企业标准版（Beta）	Java、C#、Go、Python	JavaScript、TypeScript、Vue、React
企业专属版	Java、C#、Go、Python	JavaScript、TypeScript、Vue、React

管理员如何准备高质量企业代码库

为确保代码数据的有效处理，我们建议您遵循以下指导原则来准备代码库。这将有助于提升检索的效率与准确性。

准备指南

上传限制仅适用于源代码文件，代码库中应仅上传实际编写的源代码文件。例如，对于Java应上传.java文件，对于C#应上传.cs文件，对于JavaScript应上传.js或.jsx文件等。
请避免上传以下内容。
- 测试数据与代码：请勿上传测试脚本、测试用例或任何不包含业务逻辑的测试相关代码。
- Mock方法：排除所有由模拟方法和工具生成的代码，除非这些代码包含对业务逻辑的具体实现。
- 构建产物：
  - 前端：排除通过构建工具（如Webpack、Gulp等）生成的文件，这些文件通常位于dist或build目录下。
  - 后端：排除编译生成的DLL文件及其他所有编译输出。
注释要求如下。
- 对希望被检索到的函数，在函数头部应添加详尽的注释。
- 注释应提供充分的信息以区分不同的函数，建议参考注释模板或根据企业规范进行相应调整。
```
/*** 更新指定订单状态。** @param orderId 订单的唯一标识符。* @param newStatus 新的订单状态。* @return boolean 表示更新是否成功。*/
```
函数名称规范要求。
- 如果函数注释较为简单，则函数名称必须能够准确描述其功能。
- 使用清晰且具描述性的命名方式，例如：exportOrdersToPDF、updateOrderStatus而不是 func1。

上传指南

打包压缩文件：将代码文件打包为.zip、.gz或.tar.gz格式。
代码包大小限制：每个代码包的大小不得超过100 MB。

开发者如何使用企业代码生成增强

插件版本要求

仅适用于 VS Code 1.3.9 及以上版本，以及 JetBrains IDEs 1.3.10 及以上版本。

后端场景使用实践

通过自然语言注释生成代码。
1. 企业代码库代码上传：上传包含所需功能代码的压缩包至企业代码库，例如雪花算法的代码，并确保目标函数遵循注释规范，注释位于函数头部。更详细代码库准备指南请参见上述管理员如何准备高质量企业代码库。
```
/*** 使用雪花算法生成唯一序列号* @param workerId* @return
*/
public synchronized Long getSnowFlowerId(long workerId){long id = -1L;if (workerId < 0 || workerId > snowFlowerProperties.getMaxWorkerId()) {throw new IllegalArgumentException(String.valueOf("workerID must gte 0 and lte " + snowFlowerProperties.getMaxWorkerId()));}// ... 算法实现代码 ...return id;
}
```
2. 输入注释：在集成开发环境（IDE）中定位到某Java类内，输入与期望召回的函数相匹配的注释。注释格式可以灵活，但应确保含义的准确性和一致性。
  
  第一种方式
  
  第二种方式
```
//请通过雪花算法生成唯一编号的代码，返回生成的id
```
  注释说明。
  - 注释长度要求：在编写代码时，注释应尽量避免过于简短，建议长度至少15个字符，过短的注释将无法触发召回。
  - 注释语义要求：确保注释的语义准确且有意义，最好包含关键词与返回值说明，以便通义灵码准确地理解和匹配相应的代码。
  - 多语言支持：支持中英文注释，代码库中的注释和实际编码时的注释可以使用不同的语言。
  - 参数名称灵活性：参数名称可以灵活处理，通义灵码会根据提供的参数自动调整以匹配召回的代码。如下反例。
    - //雪花算法问题：没有提供足够的信息，注释长度过短。
    - //生成唯一序列号问题：没有使用具体关键词，可能会影响理解和匹配效果。
3. 代码生成：首次回车后，灵码将提供基于注释生成补全建议；再次回车后，灵码将根据企业代码库中的代码进行补全。
  
  说明
  - 如果您的注释中包含参数，灵码将自动调整生成代码中的参数，确保命名一致性。
  - 如果需要刷新缓存获取新的补全建议，macOS可以使用⌥(option) P 手动触发行间补全，Windows可以使用Alt P手动触发。
通过函数签名生成代码。
1. 代码库代码上传：上传包含所需功能代码的压缩包至企业代码库，并确保这些函数具有清晰且独特的标识，以便于检索和识别。更详细代码库准备指南请参见上述管理员如何准备高质量企业代码库。
2. 输入函数签名：在集成开发环境（IDE）中定位到某Java类内，键入目标函数的签名部分。参数名称可以灵活处理，通义灵码会根据提供的参数自动调整以匹配召回的代码。
```
public List<Object> nextList(String name, int size)
```
  函数签名说明。
  - 函数名称：使用较为清晰的函数名称，需要具备一定语义作为相似性依据。
  - 参数和返回值：类型和顺序需要与目标函数保持一致，但参数名称可以灵活处理，通义灵码会根据提供的参数自动调整以匹配召回的代码。如下反例。
    - public List<Object> func1(String name, int size)// 问题：函数名语义不清晰，无法准确反映函数功能
    - public List<String> nextList(int orderId)// 问题：参数类型和返回值类型，与目标函数不匹配
3. 代码补全：首次回车后，灵码将提供代码补全建议；再次回车后，灵码将根据企业代码库中的代码进行自动补全。
  
  说明
  - 灵码将根据您提供的参数名，自动调整生成代码中的参数名，确保命名一致性。
  - 如果需要刷新缓存获取新的补全建议，macOS可以使用⌥(option) P 手动触发行间补全，Windows可以使用Alt P手动触发。

前端场景使用实践

通过标签补全前端自研组件代码。
1. 代码库代码上传：在开始之前，您需要确保所有必要的前端组件代码已经上传到企业代码库中。如下是React框架示例。
```
<LTableisReady={isReady}formInitialValues={formInitialValues}rowKey="key"tableRef={tableRef}toolbarLeft={<Button type="primary">新增</Button>}formItems={formItems}formRef={formRef}columns={columns}request={async (params, requestType) => {const res: Record<string, any> = await apiGetUserList(params);return {data: res.data,total: res.total,};}}
/>
```
2. 编写组件代码：在您的IDE中打开相应的.jsx文件，并开始编写代码。输入基础HTML标签或自定义组件标签，例如 <LTable /> 。
3. 代码自动补全：当您输入的代码达到一定长度，并且能够与企业组件库中的代码匹配时，IDE将自动触发代码补全功能，为您生成完整的组件代码。您也可以通过回车，主动触发代码补全。
  
  重要
  
  请在完整的组件标签内触发您的补全。
通过自然语言注释生成代码。
1. 代码库代码上传：上传包含所需功能代码的压缩包至企业代码库，并确保每个函数都遵循注释规范，注释位于函数头部。更详细代码库准备指南见管理员如何准备高质量企业代码库章节。如下是JavaScript示例。
```
/*** 根据报错信息生成，以id为键值的对象* @param {Array<validator,Result>} results* @return {Record<string,string>}
*/
function getErrObj(results) {// ... 函数实现代码 ...
}
```
2. 输入注释：在IDE中，在JavaScript文件内输入特定的注释内容，如下示例。
```
//根据报错信息生成以 id 为键值的对象
```
  注释说明。
  - 注释长度要求：在编写代码时，注释应尽量避免过于简短，建议长度至少15个字符，过短的注释将无法触发召回。
  - 注释语义要求：确保注释的语义准确且有意义，最好包含关键词与返回值说明，以便通义灵码准确地理解和匹配相应的代码。
  - 多语言支持：支持中英文注释，代码库中的注释和实际编码时的注释可以使用不同的语言。
  - 参数名称灵活性：参数名称可以灵活处理，通义灵码会根据提供的参数自动调整以匹配召回的代码。
3. 代码生成：首次回车后，灵码将提供基于注释生成补全建议；再次回车后，灵码将根据企业代码库中的代码进行补全。