bdware/bdcontract-doc
2
0
Fork 0
mirror of https://gitee.com/BDWare/bdcontract-doc synced 2026-02-15 04:39:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

release 1.4.5

Browse Source
This commit is contained in:
CaiHQ
2022-01-04 13:14:02 +08:00
parent 47b3b7b395
commit 91b28aee61
8 changed files with 961 additions and 655 deletions
Download Patch File Download Diff File Expand all files Collapse all files

348
source/YJSAPI.rst
View File

@@ -68,7 +68,7 @@ YJS Build-in API
}
发布事件 pubEvent
~~~~~~~~~~~~~~~~~
-----------------
参数
@@ -86,7 +86,7 @@ YJS Build-in API
return "done";
}
也可以在合约开头声明事件，则事件名即为事件主题，此时可直接使用事件作为方法名发布事件
也可以在合约开头定义事件，则事件名即为事件主题，此时可直接使用事件作为方法名发布事件
.. code:: javascript
@@ -98,55 +98,6 @@ YJS Build-in API
该写法与上面的\ ``pub1``\ 等价。
发布带语义事件 pubEventConstraint
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
参数
.. code:: bash
topic：字符串类型，发布的事件主题
content：字符串类型，发布的事件内容
semantics：枚举类型，作为字符串输入，事件语义
事件语义参数 + AT_LEAST_ONCE：至少一次，默认语义 +
AT_MOST_ONCE：至多一次 + ONLY_ONCE：只有一次
使用示例：
.. code:: javascript
export function pub1(arg) {
YancloudUtil.pubEventConstraint("topic", arg, "AT_MOST_ONCE");
return "done";
}
也可以在合约开头声明事件，则事件名即为事件主题，此时可直接使用事件作为方法名按声明的语义发布事件
.. code:: javascript
event AT_MOST_ONCE topic;
export function pub2(arg) {
topic(arg);
return "done";
}
该写法与上面的\ ``pub1``\ 等价。
事先声明的事件无论是否声明语义，都可以用后缀s作为方法名的方式调用，发布任意语义的事件：
.. code:: javascript
event topic;
export function pub3(arg) {
topics(arg, "AT_MOST_ONCE");
return "done";
}
该写法与上面的\ ``pub1, pub2``\ 等价。
*不带事件语义声明事件时，语义默认为至少一次（AT_LEAST_ONCE）。*
访问资源文件
~~~~~~~~~~~~
@@ -182,30 +133,6 @@ loadAsScanner
var scanner = Global.Resources.loadAsScanner("/local.txt");
YancloudUtil
~~~~~~~~~~~~
提供了一些内置的工具方法。
getKeyPair
^^^^^^^^^^
参数：
::
无
使用示例：
::
var keyPair = YancloudUtil.getKeyPair();
//该类型为SM2KeyPair类型，
print(keyPair.getPublicKeyStr());
print(keyPair.getPrivateKeyStr());
print(keyPair.toJson());
YJS Build-in Annotation
-----------------------
@@ -325,15 +252,13 @@ LogType注解通过参数的方式声明合约或函数的需要记录的日志
::
@integer 整数
@string 字符串
@boolean 布尔值
@date @time @datatime
@word 单词 @cword 中文单词
@first @last 英文姓，名
@cfirst @clast @cname 中文姓，名，全名
@url @domin @ip @email
@region @province @city @county 地区，省，市，县
@integer
@string
@boolean
@date
@time
@datatime
/[a-z][A-Z][0-9]/ （正则表达式）
……
详细格式可以参考http://mockjs.com/examples.html
@@ -341,10 +266,20 @@ LogType注解通过参数的方式声明合约或函数的需要记录的日志
.. code:: json
//返回一个1-100之间的整数
@MockTemplate({'result|1-100':1})
//返回
{'result':76}
//返回一个1-5个数的数组
@MockTemplate({'result|1-5':[{'value|1-100':1}]})
//返回
{"result":[{"value":34},{"value":8},{"value":48},{"value":50},{"value":43}]}
//返回一个对象包含如下字段
@MockTemplate({'result':{'id':'@integer','email':'@email','password':'@string','name':'@name'}})
//返回
{"password":"3ZLc","name":"William Young","id":36097783842688,"email":"d.fuunwe@gqnr.to"}"
{"password":"3ZLc","name":"William Young","id":36097783842688,"email":"d.fuunwe@gqnr.to"}
//返回元素个数为1-5个之间的一个数组，数组的每个元素都是上述格式的一个对象
@@ -374,6 +309,7 @@ LogType注解通过参数的方式声明合约或函数的需要记录的日志
~~~~~~~
该注解可以修饰\ ``function``\ 。
若没有模拟数据模板，则返回模拟数据时使用该注解的内容
提供函数的返回结果示例，若加此注解则生成说明文档时将直接返回此结果而不使用默认参数调用函数。
::
@@ -390,16 +326,6 @@ LogType注解通过参数的方式声明合约或函数的需要记录的日志
return JSON.stringify(c);
}
@Cost
~~~~~
该注解可以修饰\ ``function``\ 。 提供函数的cpu计量功能。
::
@Cost({"countGas":true})
export function ....
IO工具类
--------
@@ -1068,53 +994,22 @@ update
var digitalObject = JSON.parse("{\"doID\":\"86.5000.470/do.hello\",\"doBody\":\"hello world\"}");
var ret = DOIPUtil.update(digitalObject);
SQLUtil
~~~~~~~
MySQLUtil
~~~~~~~~~
可以使用@Permission(“SQL”)来引入SQLUtil对象。
可支持MySQL/PostgreSQL/Oracle/GuassDB200等SQL数据库。
需要将对应的jdbc的jar上传到项目中。
例如，要使用mysql，可上传mysql-connector-java-8.0.24.jar
可以使用@Permission(“MySQL”)来引入MySQLUtil对象。
::
@Permission("SQL")
oracle MySQLExample{
@Permission("MySQL")
contract MySQLExample{
...
}
initDriver
^^^^^^^^^^
.. _参数-21:
参数
''''
==== =========== ==========
序号 参数 说明
==== =========== ==========
1 driverClass 字符串类型
==== =========== ==========
.. _使用示例-22:
使用示例
''''''''
.. code:: javascript
//使用mysql
SQLUtil.initDriver("com.mysql.cj.jdbc.Driver");
//使用postgresql
SQLUtil.initDriver("org.postgresql.Driver");
//使用oracle
SQLUtil.initDriver("oracle.jdbc.OracleDriver");
getConnection
^^^^^^^^^^^^^
.. _参数-22:
.. _参数-21:
参数
''''
@@ -1127,7 +1022,7 @@ getConnection
3 pwd 字符串类型，密码
==== ======= ====================
.. _使用示例-23:
.. _使用示例-22:
使用示例
''''''''
@@ -1138,7 +1033,7 @@ getConnection
var usrName = "xxx";
var pwd = "xxx";
//配置好用户名和密码，url格式为ip或域名+端口，中间以”:”隔开。
var conn = SQLUtil.getConnection(url,usrName,pwd);
var conn = MySQLUtil.getConnection(url,usrName,pwd);
//获取数据库连接
var sql = "select * from newele.data";
//创建查询语句
@@ -1176,7 +1071,7 @@ MongoDBUtil
getConnection
^^^^^^^^^^^^^
.. _参数-23:
.. _参数-22:
参数
''''
@@ -1191,7 +1086,7 @@ getConnection
5 pwd 字符串类型 数据库的密码
==== ======= =========================
.. _使用示例-24:
.. _使用示例-23:
使用示例
''''''''
@@ -1233,7 +1128,7 @@ loadDB
通过loadDB来加载一个RocksDB数据库。 加载后，可进行get/delete/put等操作。
.. _参数-24:
.. _参数-23:
参数
''''
@@ -1245,7 +1140,7 @@ loadDB
2 readOnly 布尔类型 数据库只读
==== ======== ===========================
.. _使用示例-25:
.. _使用示例-24:
使用示例
''''''''
@@ -1360,14 +1255,14 @@ generateKeyPair
生成公私钥。
.. _参数-25:
.. _参数-24:
参数
''''
无参数。
.. _使用示例-26:
.. _使用示例-25:
使用示例
''''''''
@@ -1384,7 +1279,7 @@ sign
签名。
.. _参数-26:
.. _参数-25:
参数
''''
@@ -1396,7 +1291,7 @@ sign
2 keyPair sm2
==== ======= ===========================
.. _使用示例-27:
.. _使用示例-26:
使用示例
''''''''
@@ -1416,7 +1311,7 @@ verify
验签。
.. _参数-27:
.. _参数-26:
参数
''''
@@ -1429,7 +1324,7 @@ verify
3 publicKey 字符串类型 公钥
==== ========= =======================
.. _使用示例-28:
.. _使用示例-27:
使用示例
''''''''
@@ -1442,60 +1337,6 @@ verify
print(ret.status);
print(ret.result);
encrypt
^^^^^^^
sm2加密。
.. _参数-28:
参数
''''
==== ========= =======================
序号 参数 说明
==== ========= =======================
1 content 字符串类型 待验签的内容
3 publicKey 字符串类型 公钥
==== ========= =======================
.. _使用示例-29:
使用示例
''''''''
.. code:: javascript
var ret = SM2Util.encrypt("Hello","...公钥");
print(ret);
decrypt
^^^^^^^
sm2解密。
.. _参数-29:
参数
''''
==== ========== =======================
序号 参数 说明
==== ========== =======================
1 content 字符串类型 待验签的内容
3 privateKey 字符串类型 公钥
==== ========== =======================
.. _使用示例-30:
使用示例
''''''''
.. code:: javascript
var ret = SM2Util.decrypt("Hello","...私钥");
print(ret);
多线程工具类
------------
@@ -1529,7 +1370,7 @@ AsyncUtil
postFunction
^^^^^^^^^^^^
.. _参数-30:
.. _参数-27:
参数
''''
@@ -1541,7 +1382,7 @@ postFunction
2 arg1 对象
==== ==== ==============
.. _使用示例-31:
.. _使用示例-28:
使用示例
''''''''
@@ -1553,7 +1394,7 @@ postFunction
setInterval
^^^^^^^^^^^
.. _参数-31:
.. _参数-28:
参数
''''
@@ -1567,7 +1408,7 @@ setInterval
4 arg3 对象
==== ==== ==============
.. _使用示例-32:
.. _使用示例-29:
使用示例
''''''''
@@ -1579,7 +1420,7 @@ setInterval
setTimeOut
^^^^^^^^^^
.. _参数-32:
.. _参数-29:
参数
''''
@@ -1592,7 +1433,7 @@ setTimeOut
3 arg2 Object
==== ==== ==============
.. _使用示例-33:
.. _使用示例-30:
使用示例
''''''''
@@ -1604,7 +1445,7 @@ setTimeOut
sleep
^^^^^
.. _参数-33:
.. _参数-30:
参数
''''
@@ -1615,7 +1456,7 @@ sleep
1 arg0 long
==== ==== ====
.. _使用示例-34:
.. _使用示例-31:
使用示例
''''''''
@@ -1642,98 +1483,3 @@ YJS支持ECMAScript6的部分内置对象 ：
- Error https://www.w3schools.com/js/js_errors.asp
- JSON https://www.w3schools.com/js/js_json.asp
YJS应用框架
-----------
ypk项目组成
~~~~~~~~~~~
如之前描述，ypk中可存放静态资源文件（html/css/js)，在智能合约中声明loadResource方法，可返回静态资源文件。
基于loadResource，本项目提供了一个yjs应用框架。
该框架可以将合约ypk中的(html/css/js)文件通过executeContract调用，加载至前端并展示。
函数约定
~~~~~~~~
==== ============ ======================================================
序号 合约函数名 说明
==== ============ ======================================================
1 needRender 不会被调用，有该函数表示需要渲染前端
2 getMainFrame 无参数，返回结果为String类型，表示主页的html文件路径
3 loadResource 参数为String，以文本形式，返回相对路径下的静态资源文件
==== ============ ======================================================
加载流程
~~~~~~~~
前端加载的参数会解析至global.urlparam。 包括以下参数：
::
//global.urlparam对象示例
{
"contract":"TrustedStorage0899", //表示合约ID或是合约的名称
"keys":{ //表示当前登录者的密钥对
"privateKey":"ff38dd04710...",
"publicKey":"04fc228..."
},
"nodeAddr":"022.node.internetapi.cn:21030" //节点的ip+端口
}
加载前会先建立与nodeAddr的websocket连接。 连接建立后，加载流程分为两步：
第一步是用当前的publickey-privatekey登录。登录过程详见\ ``BDContract SDK``
的 ``合约节点WebSocket接口`` 登录之后，会获取合约的信息。
并存放于global.currentContract对象。
第二步，是根据global.currentContract对象中，是否有needRender方法，
如果有，就会进入加载前端代码的流程。
具体为1.执行executeCurrentContract(“getMainFrame”)
获取页面的html，append至mainDIV之后，
会解析所有\ ``<script>``,\ ``<link>``\ 等标签。2.会以标签中的\ ``fromContract``\ 属性，去调用executeCurrentContract(“loadResources”)方法。
典型的yjs的loadResources方法如下。3.获取所有script会进行eval,link会当css加载。
::
//在某个yjs文件中声明。
export function loadResource(arg){
return Global.Resources.loadAsString(arg);
}
.. figure:: ./_static/imgs/clientLoadProcess.png
:alt: 前端加载流程图
前端加载流程图
前端框架预置函数说明
~~~~~~~~~~~~~~~~~~~~
前端的javascript在html中已加载了jquery(使用$.)和vue2。
为避免冲突，本版不支持再加载vue2/vue3脚本。
前端通过executeContract/executeCurrentContract与后端交互。
executeContract
^^^^^^^^^^^^^^^
调用某个合约的某个函数。会自动使用当前的global.sm2Key进行签名。参数说明及示例：
.. code:: javascript
executeContract(contracID,operation,arg,callback);
//其中，contractID为string类型，为被调用的合约名称/合约ID。
//operation为string类型，合约函数
//arg为string类型，表示参数
//callback为函数类型，接受返回结果的回调函数。
executeCurrentContract
^^^^^^^^^^^^^^^^^^^^^^
执行当前合约的某个函数。会自动使用当前的global.sm2Key进行签名。参数说明及示例：
.. code:: javascript
executeContract(operation,arg,callback);
//operation为string类型，合约函数
//arg为string类型，表示参数
//callback为函数类型，接受返回结果的回调函数。