输入规范文件

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:

区块链应用程序构建器支持两种特殊资产类型，即嵌入式资产和令牌资产，以及没有指定类型的通用资产。特殊资产在规范文件的 assets: 部分下定义为 type: embedded 或 type: token。

表 7-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:

将根据 Blockchain App Builder 提供的某些现成验证来验证给定属性。如果确保链有效，则可以链接验证。

如果未提供 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:

type：字符串
  • min()
  • max()
  • email()
  • url()
  • /regex/ - 支持 PHP regex

对于 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:

类型：boolean
  • 真
  • 假

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

name: active
type: boolean
validate:

类型：数组

通过键入本身，以 type: 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 (Create/Read/Update/Delete) 或其他方法。

默认情况下，如果未输入任何内容，将生成所有 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" （开始）。

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

如果根本不使用 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)"