输入规范文件

Blockchain App Builder 初始化命令读取输入规范文件并生成基架项目，其中包括用于帮助链代码开发过程的工具。

在规范文件中，您可以指定多个资产定义和行为、CRUD 和非 CRUD 方法声明、定制方法、参数验证、自动编集/解编集、透明持久性功能，以及使用 SQL SELECT 语句或 CouchDB 查询语言完成富数据查询的功能。这些功能是为您生成的。

有关指定令牌资产的信息，请参见以下主题：
规范文件可以采用 YAML 或 JSON 格式写入。您可以在 Blockchain App Builder 软件包下载中查看两种格式的示例规范文件：
  • Fabcar-Typescript.yml
  • Marbles-Go.yml

注意：

根据 Go 约定，导出的名称以大写字母开头。因此，所有资产属性和方法的名称在规范文件中必须以大写字母开头。

规范文件的结构

通常，您可以按以下方式构造规范文件：

assets: 
    name:
    type:
    properties:
        name:
        type:
        id:
        derived:
           strategy:
           algorithm:
           format:
        mandatory:
        default:
        validate:
    methods:
        crud:
        others:
customMethods:

Blockchain App Builder 支持两种特殊资产类型，嵌入式资产和令牌资产，以及没有指定类型的通用资产。特殊资产在规范文件的 assets: 部分下定义为 type: embedded 或 type: token。

表 3-2 规范文件参数说明和示例

进入 说明 示例
assets:

此属性接受资产的定义和行为。可以定义多个资产。

  
name:

资产的名称。

保留以下名称。请勿将这些名称用于资产。
  • account
  • role
  • hold
  • token
  • authorization
  • tokenAdmin
  • Account
  • Role
  • Hold
  • Token
  • Authorization
  • TokenAdmin
 
name: owner # Information about the owner
type:

资产类型

支持以下特殊资产类型：
  • embedded
  • token

如果未在 assets 部分中指定 type 参数，则资产属于通用类型。

 
type:

类型：嵌入式

如果此属性设置为 embedded，则资产定义为嵌入式资产。嵌入式资产没有 CRUD 方法，并且必须是要存储在分类账中的另一资产的一部分。

在本示例中，嵌入了属性 address，并在其他资产中定义了该属性。

嵌入式资产不支持循环引用。例如，在上一个示例中，address 资产不能包含对 employee 资产的引用。

资产：employee
name: employee
  properties:
     name: employeeId
     type: string
     mandatory: true
     id: true

     name: firstName
     type: string
     validate: max(30)
     mandatory: true

     name: lastName
     type: string
     validate: max(30)
     mandatory: true

     name: age
     type: number
     validate: positive(),min(18)

     name: address
     type: address
资产：address
name: address

type: embedded

properties:
   name: street
   type: string

   name: city
   type: string

   name: state
   type: string

   name: country
   type: string
properties:

描述资产的所有属性。

  
name:

属性的名称。

 
name: ownerId # Unique ID for each owner
id:
  • 真

此项指定此资产的标识符。此属性为强制属性。

 
name: owner            # Information about the owner
properties:
     name: ownerId    # Unique ID for each owner
     type: string
     mandatory: true
     id: true
     name: name        # Name of the owner
     type: string
     mandatory: true
type:

财产类型

支持以下基本属性类型：
  • number
  • float
  • string
  • boolean
  • date
  • array
对于 Go 链代码，number 映射到 int，float 映射到 float64。当前不支持其他类型，包括以下类型：
  • complex
  • unsigned/signed int
  • 8/16/32/64 bits
 
name: year        # Model year
                    type: number
                    mandatory: true
                    validate: min(1910),max(2020)
                    name: color       # Color - no validation as color names are innumerable
                    type: string
                    mandatory: true
derived:

此属性指定 id 属性派生自其他密钥。相关属性必须为 string 数据类型，而不是嵌入式资产。

此属性有两个必需的参数：
  • strategy：接受 concat 或 hash 的值。
  • format：获取要由策略使用的规范字符串和值的数组。
示例 1：
  • 属性 employeeID 依赖于 firstName 和 lastName 属性。
  • 此属性是 format 数组中列出的值的串联。
  • IND%1#%2%tIND 是数组中的第 0 个索引，用于描述最终格式。
  • %n 是位置说明符，用于从数组中的其他索引获取其值。
  • %t 指示该值是通道标头中的 stub.timestamp 值。
  • 如果需要在 format 字符串中使用百分号 (%)，则必须使用另一个百分号 (%) 对其进行转义。
  • 本示例中的最终格式为：INDfirstName#lastName1606885454916IND
示例 2：
  • 使用 hash 时，还必须使用 algorithm 参数。缺省值为 sha256；还支持 md5。
  • IND%1#%2%t 是数组中的第 0 个索引，用于描述最终格式。
  • %n 是位置说明符，用于从数组中的其他索引获取其值。
  • %t 指示该值是通道标头中的 stub.timestamp 值。
  • 如果需要在 format 字符串中使用百分号 (%)，则必须使用另一个百分号 (%) 对其进行转义。
示例 1
name: employee
  properties:
     name: employeeId
     type: string
     mandatory: true
     id: true
     derived:
         strategy: concat
         format: ["IND%1#%2%tIND","firstName","lastName"]

     name: firstName
     type: string
     validate: max(30)
     mandatory: true

     name: lastName
     type: string
     validate: max(30)
     mandatory: true

     name: age
     type: number
     validate: positive(),min(18)
示例 2
name: account
  properties:
     name: accountId
     type: string
     mandatory: true
     id: true
     derived:
         strategy: hash
         algorithm: 'sha256'
         format: ["IND%1#%2%t","bankName","ifsccode"]

     name: bankName
     type: string
     validate: max(30)
     mandatory: true

     name: ifsccode
     type: string
     mandatory: true
mandatory:
  • 真
  • 假

对应的属性为必填项，无法在创建资产时跳过。

 
name: phone       # Phone number - validate as (ddd)-ddd-dddd where dashes could also be periods or spaces
type: string
mandatory: true
validate: /^\(?([0-9]{3})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$/
name: cars        # The list of car VINs owned by this owner
type: string[]
mandatory: false
default:

此属性的缺省值。

  
validate:

给定属性将根据区块链应用构建器提供的某些现成可用验证进行验证。如果确保链有效，则可以链接验证。

如果未提供 validate 属性，则仅对属性 type 执行验证。

 
validate:

类型：数字
  • 正()
  • negative()
  • min()
  • max()

这些验证可以链接在一起，以逗号分隔。 

name: offerApplied
type: number
validate: negative(),min(-4)
name: year  # Model year
type: number
mandatory: true
validate: min(1910),max(2020)
validate:

类型：字符串
  • min()
  • max()
  • email()
  • url()
  • /regex/ 支持 PHP 正则表达式

对于 Go 链代码，必须正确转义包含某些保留字符或空格字符的正则表达式。

 
name: website 
type: string
mandatory: false
validate: url()
name: phone  # Phone number - validate as (ddd)-ddd-dddd where dashes could also be periods or spaces
type: string
mandatory: true
validate: /^\(?([0-9]{3})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$/
name: Color #Color can be red, blue, or green
type: string
mandatory: true
validate: /^\\s*(red|blue|green)\\s*$/
validate:

类型：布尔
  • 真
  • 假

在示例中，属性 active 的验证按类型本身 (boolean) 进行 

name: active
type: boolean
validate:

类型：数组

通过键入自身，以 type: number[] 的形式，这表示数组为 number 类型。

可以按 number[1:5] 格式输入数组的限制，这意味着最小长度为 1，最大长度为 5。你可以忽略其中一个。 

name: items
type: number[:5]
validate:

类型：日期
  • min()
  • max()
日期必须为以下格式之一：
  • YYYY-MM-DD
  • YYYY-MM-DDTHH:MM:SSZ，其中 T 将日期与时间分隔开，Z 表示 UTC。时区偏移可以替换 Z，如“中央夏令时”的 -05:00。 
name: expiryDate
type: date
validate: max('2020-06-26')
name: completionDate
type: date
validate: min('2020-06-26T02:30:55Z')
methods:

使用此项可说明要生成的 CRUD（创建/读取/更新/删除）或其他方法。

默认情况下，将生成所有 CRUD 和其他方法。

 
methods:
    crud: [create, getById, update, delete]
    others: [getHistoryById, getByRange]
crud:
  • create
  • getByID（已读）
  • update
  • delete

如果此数组留空，则不会创建 CRUD 方法。

如果未指定 crud 参数，则默认情况下将创建所有四个方法。

crud 参数不适用于 token 和 embedded 资产。 

methods:
    crud: [create, getById, delete]
    others: [] # no other methods will be created
others:
  • getHistoryById
  • getByRange

getHistoryById 返回列表中的资产历史记录。

getByRange 返回给定范围内的所有资产。有关详细信息，请参阅 "getByRange" (TypeScript) 和 "GetByRange" (Go)。

如果此数组留空，则不会创建其他方法。

如果根本不使用 others 参数，则默认情况下将创建这两个方法。

others 参数不适用于 token 和 embedded 资产。 

methods:
    crud: [create, delete]
    others: [] # no other methods will be created
      methods:
        crud: [create, getById, update, delete]
        others: [getHistoryById, getByRange]
customMethods:

此属性在主控制器文件中创建可调用的定制方法模板。它接受方法签名，并在控制器文件中创建函数声明。

您可以在此处提供特定于语言的函数声明。

提供了名为 executeQuery 的定制方法。如果将此方法添加到规范文件中，则会详细说明如何执行 Berkeley DB SQL 和 CouchDB 富查询。仅当您连接到 Oracle Blockchain Platform Cloud 或 Enterprise Edition 时，才能计算此方法。

TypeScript

customMethods:
    - executeQuery
    - "buyCar(vin: string, buyerId: string, sellerId: string, price: number, date: Date)"
    - "addCar(vin: string, dealerId: string, price: number, date: Date)"

开始

customMethods:
    - executeQuery
    - "BuyCar(vin string, buyerId string, sellerId string, price int)"
    - "AddCar(vin string, dealerId string, price int)"